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://postgres:postgres@localhost:5432/veref
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

API falls back to preview data

Cause:

• Prisma is unavailable, not migrated, or failed during a request

What to expect:

• dashboard and reference-request flows may still return preview-oriented responses
• this is a fallback, not proof that persistence is healthy

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.

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

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.

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

Desktop shows broken workspace links

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

Surface links point at the wrong place

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.