Troubleshooting

Common issues and how to fix them.

Provider connection errors

Symptom: Requests return {"error": "provider error: connection refused"}

Fix: Check that your provider API key is set. Run stockyard doctor to verify all configured providers are reachable.

stockyard doctor
# Shows provider connectivity, key validity, and config status

Port already in use

Symptom: server: listen tcp :4200: bind: address already in use

Fix: Another process is using port 4200. Either stop it or change Stockyard's port:

PORT=8080 stockyard

No providers detected

Symptom: Stockyard starts but requests fail with "no provider configured"

Fix: Set at least one provider API key as an environment variable before starting Stockyard. See environment variables for the full list.

export OPENAI_API_KEY=sk-...
stockyard

Auth errors on /v1/* requests

Symptom: Requests to /v1/chat/completions return 401

Fix: If STOCKYARD_REQUIRE_AUTH=true, you need to create a user key and include it in your requests. To disable auth for development:

STOCKYARD_REQUIRE_AUTH=false stockyard

Database errors

Symptom: database: unable to open database file

Fix: The data directory does not exist or is not writable. Create it or set DATA_DIR to a writable path:

mkdir -p /data
DATA_DIR=/data stockyard

Railway deployment issues

Symptom: Deploy succeeds but the service crashes on startup

Fix: Ensure railway.toml has startCommand = "stockyard". Do not use a VOLUME directive in Dockerfile (Railway rejects it). Set up a persistent volume in the Railway dashboard and Stockyard auto-detects it via RAILWAY_VOLUME_MOUNT_PATH.

Enable debug logging

For detailed request/response logging:

LOG_LEVEL=debug stockyard

For JSON-formatted logs (useful for log aggregation):

LOG_LEVEL=debug LOG_FORMAT=json stockyard

Run the doctor

stockyard doctor checks everything: provider connectivity, database health, config validity, port availability, and system requirements. Run it first when debugging any issue.