Skip to Content
Troubleshooting

Troubleshooting

This page covers the most likely setup and runtime failures for contributors onboarding into the repo.

Database problems

DATABASE_URL is not configured

Cause:

  • API Prisma service could not create a client because DATABASE_URL is missing

Fix:

export DATABASE_URL=postgres://veref:postgres@localhost:5432/veref_dev
bun run db:generate

If the database exists but schema tables do not, run one of:

bun run db:migrate:dev
bun run db:push

Ops API says database is required

Cause:

  • Prisma is unavailable, not migrated, or failed during an ops feed or ops message request

Fix:

  • configure DATABASE_URL
  • run migrations or bun run db:push
  • only for local development, set VEREF_ENABLE_PREVIEW_FALLBACK=1 to use preview ops data

Clerk problems

Recruiter auth is not fully configured

Cause:

  • CLERK_SECRET_KEY or NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is missing

Fix:

  • set both keys
  • restart the affected Next.js process

If you are only exploring local product structure, missing keys may not block all understanding, but they do mean you are not running a fully configured auth path.

CLI login problems

veref login opens the wrong app or API

Cause:

  • local or staging URLs are not configured
  • stored CLI credentials were created against another environment

Fix:

veref logout
veref login --api-url http://localhost:8787 --app-url http://localhost:3000

Production login does not need URL flags:

veref login

CLI cannot store credentials

Cause:

  • the platform does not have supported secure credential storage

Fix:

  • use VEREF_API_KEY for non-interactive runs
  • on local machines only, opt into file storage with VEREF_ALLOW_PLAINTEXT_CLI_CREDENTIALS=1

OpenRouter problems

LLM output says OpenRouter is not configured

Cause:

  • OPENROUTER_API_KEY is missing

Fix:

export OPENROUTER_API_KEY=...

Optional override:

export OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
export OPENROUTER_CHAT_MODEL=openai/gpt-oss-20b:free
export OPENROUTER_MODEL_CHAIN=openai/gpt-oss-20b:free,openrouter/free

The repo is designed to return an unconfigured response instead of failing hard, so treat that message as a real setup signal.

Messaging problems

Email or SMS never leaves preview mode

Cause:

  • Resend or Twilio credentials are absent

Fix:

  • set RESEND_API_KEY for email
  • set TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_MESSAGING_SERVICE_SID for SMS

Without those values, communication previews are still expected locally.

Desktop bridge problems

Desktop bridge unavailable. The preload API did not attach to window.verefDesktop.

Cause:

  • Electron preload bridge is not loaded correctly or the desktop app was not started through the intended runtime path

Fix:

bun run dev:desktop

Then confirm the desktop build artifacts and preload entrypoints are available.

dev:desktop loads the cloud app by default. If it shows a blank draggable splash, check for an unreachable explicit VEREF_DESKTOP_APP_URL; generic local app env vars do not control desktop.

Desktop shows agents unavailable

Cause:

  • claude and or codex is not installed or not on PATH

Fix:

  • run claude --version
  • run codex --version
  • restart the desktop app after fixing the local shell environment

Cause:

  • .claude or .codex symlinks are missing or no longer point at .agents/*

Fix:

./skills.sh install
./skills.sh status

Extension configuration problems

Extension opens the wrong recruiter app URL

Cause:

  • PLASMO_PUBLIC_APP_URL is unset or points at the wrong environment

Fix:

  • set PLASMO_PUBLIC_APP_URL to the correct app base URL
  • reload the extension

Local fallback is http://localhost:3000, so a mismatch usually shows up when the recruiter app is running elsewhere.

Docs and local URL mismatches

Cause:

  • NEXT_PUBLIC_APP_URL, NEXT_PUBLIC_WEB_URL, or NEXT_PUBLIC_DOCS_URL does not match the running local ports

Fix:

  • align the env values with the actual local processes
  • use the repo defaults unless you intentionally changed ports

Build verification problems

next build says another build is already running

Cause:

  • a prior Next.js build process is still active or did not exit cleanly

Fix:

  • wait for the previous build to finish
  • if it is stale, stop the old build process and rerun the command once

Repo verify fails after docs edits

Fix order:

  1. Run bun run --filter @veref/docs build to isolate docs issues.
  2. Run bun run typecheck.
  3. Run bun run test.
  4. Run bun run build.

If the docs build passes but repo-wide build fails, the issue is outside the docs surface.

Agent CLIDeployment & Operations