piyaz
Help

Troubleshooting

Fixes for the errors you hit setting up Piyaz: port 3000 in use, Postgres refusing connections, db:migrate failures, and MCP tools missing in Claude Code.

Common issues when setting up or running Piyaz. If your problem is not listed here, open a GitHub issue.

Port 3000 already in use (EADDRINUSE)

Symptom: bun run dev fails with Error: listen EADDRINUSE: address already in use :::3000.

Fix: Find and kill the process occupying port 3000:

lsof -i :3000
kill -9 <PID>

Then run bun run dev again.

BETTER_AUTH_SECRET too short or missing

Symptom: Authentication silently fails. Login redirects loop or sessions are not persisted.

Fix: Ensure BETTER_AUTH_SECRET in .env.local is set and at least 32 characters long. Generate one with:

openssl rand -base64 32

Restart the dev server after changing .env.local.

PostgreSQL connection refused (ECONNREFUSED)

Symptom: bun run dev or bun run db:migrate fails with connection refused or ECONNREFUSED 127.0.0.1:5432.

Fix: Check that Docker is running and the Postgres container is up:

docker compose ps

If the db service is not listed or is unhealthy, start it:

docker compose up -d

bun run db:migrate fails

Symptom: drizzle-kit migrate exits with an error about missing tables, connection issues, or the database URL being undefined.

Fix:

  1. Confirm the database connection URLs are set in .env.local (not .env).
  2. Confirm the database is reachable: run docker compose ps to check the container health.
  3. If you just started Docker, wait a few seconds for Postgres to finish initializing, then retry:
bun run db:migrate

bun run db:setup handles the wait automatically: it brings up Postgres with docker compose up --wait, which blocks until the database healthcheck passes before applying the schema.

MCP server not appearing in Claude Code

Symptom: After installing the plugin, Claude Code does not show Piyaz tools or the /piyaz skill.

Fix:

  1. Confirm the plugin is installed: 
    claude plugin marketplace add FrkAk/piyaz
claude plugin install piyaz@piyaz
  2. Run /mcp, select piyaz, and complete the browser sign-in. The tools appear once OAuth succeeds.
  3. If you self-host, confirm your own instance is running, then register it as a second server and sign in. Use your own origin in place of http://localhost:3000: 
    claude mcp add -s user --transport http piyaz-self-hosted http://localhost:3000/api/mcp
claude mcp login piyaz-self-hosted
    The bundled piyaz server points at the hosted app and never at your instance. See the self-host guide.
  4. If tools still do not appear, restart Claude Code completely.

Last updated

Run locally

Run your own Piyaz server on your machine, then point the plugin at it.

Tips and tricks

Practical habits that keep a Piyaz project fast and the graph honest.

On this page

Port 3000 already in use (EADDRINUSE)BETTER_AUTH_SECRET too short or missingPostgreSQL connection refused (ECONNREFUSED)bun run db:migrate failsMCP server not appearing in Claude Code