//DOCS Troubleshooting

Common symptoms and fixes.
GitHub Docs

Troubleshooting

Common issues while running or integrating Punk.

Port 4100 Is Already In Use

Symptom:

Port 4100 is already in use

Fix:

PUNK_PORT=4101 bun run dev

Or stop the other process using the port.

Gateway Is In Open Dev Mode

Symptom: startup prints a warning about open dev mode.

Meaning: PUNK_API_KEY is not set. This is fine locally and unsafe publicly.

Fix:

PUNK_API_KEY=your-secret bun run dev

Then send:

Authorization: Bearer your-secret

401 Unauthorized

Causes:

  • PUNK_API_KEY is set and request has no bearer token.
  • Bearer token does not match bootstrap key or tenant API key.
  • Tenant API key was revoked.

Fix:

  • Add Authorization: Bearer <token>.
  • Confirm token was copied when created; only the hash is stored.
  • Create a new key with /api/v1/keys if needed.

403 Admin Key Required

You are calling an operator route with a non-admin key.

Admin-only examples:

  • Create/revoke keys.
  • Update settings.
  • Synthesize/ignore patterns.
  • Promote/rollback/quarantine/replay artifacts.
  • Decide approvals.
  • Run learning tick.
  • Invalidate caches.

Fix: use bootstrap key or create an admin tenant key.

403 Policy Block Or Approval Required

If a policy denies the action, inspect:

  • Run route explanation.
  • /api/v1/audit.
  • /api/v1/policies.
  • policies/*.yaml.

If approval is required:

  • Check /api/v1/approvals.
  • Use dashboard or PunkBar to decide.
  • In observe mode, the same policy result is recorded but not enforced.

Web Fetch Fails

Statuses:

  • 400: invalid URL.
  • 403: private/loopback URL blocked by SSRF guard.
  • 502 with category=timeout: upstream timed out.
  • 502 with category=too_large: response exceeded size cap.
  • 502 with category=upstream: generic upstream failure.

Fixes:

  • Use public HTTP(S) URLs.
  • For local demos, run with open dev mode or set PUNK_ALLOW_PRIVATE_WEB_FETCH=true.
  • Use bypassCache=false where cache is acceptable.
  • Check whether external pages block automated fetches.

SOM Source Is builtin Instead Of The Configured AWP Engine

Meaning:

  • PLASMATE_URL is unset, or
  • the configured AWP engine failed and Punk is in temporary backoff.

Fix:

  • Start the configured AWP engine.
  • Set PLASMATE_URL=ws://127.0.0.1:9222.
  • Retry after backoff.

Punk's built-in compiler is expected fallback behavior.

Demo Does Not Optimize On First Run

Expected. Punk observes before it optimizes.

Run:

bun run demo

Then run it again. Optimized share should climb as caches, patterns, replay, shadow, and promotion evidence accumulate.

Artifact Did Not Promote

Common reasons:

  • Not enough repeated runs.
  • Replay failed.
  • Shadow failed.
  • Side-effect level is too high.
  • Human approval is pending.
  • Auto-promotion is disabled.

Check:

  • /api/v1/patterns
  • /api/v1/artifacts
  • /api/v1/approvals
  • /api/v1/learning/report

Cache Hit Did Not Happen

Possible reasons:

  • Request normalization differs.
  • Subject differs.
  • Cache expired.
  • Policy or route selected another path.
  • Pattern is negative cached.
  • Tool did not declare sideEffectLevel <= 1 and TTL.

Check the run's route explanation and /api/v1/cache/stats.

Tool Results Are Not Cached

Requirements:

  • Use SDK traceTool.
  • Set sideEffectLevel to 0 or 1.
  • Set ttlSeconds > 0.
  • Pass stable args.
  • Use the same subject/auth scope where appropriate.

Side-effecting tools are intentionally not cached.

Typecheck Or Tests Fail After Pull

Punk is active development. Start with:

bun install
bun run typecheck
bun test

If dependencies changed, bun install is usually enough. If persistent database state is the issue, move the local SQLite file aside and let Punk recreate it:

mv data/punk.db data/punk.db.bak

Do not delete production data.