Troubleshooting
Most SPAPS failures are easiest to debug by layer. Start with startup settings, then application identity, then user identity, then domain service behavior. Avoid jumping straight into a domain service until the request has made it through dependencies.
Symptom Decision Tree
| Symptom | First command | Expected signal | Likely cause | Next page |
|---|---|---|---|---|
| Local runtime will not start | npx spaps status | API URL and availability are reported | Local runtime source, port, or Docker state is unavailable | Local runtime |
| Python stack will not start | make local-proof-up && curl -fsS http://localhost:3301/health | /health responds | Startup validation, missing services, or port conflict | Deployment validation |
| API key rejected | curl -fsS http://localhost:3301/health/local-mode | Local-mode state is explicit | Missing X-API-Key, wrong key type, or local-mode assumption | Auth and local mode |
| CORS or origin failure | Inspect applications.allowed_origins for the app slug | Exact browser origin is present | Origin was changed in frontend config but not the app record | API keys and origins |
| Auth mode mismatch | npx spaps quickstart --json | Output names local-mode or provisioning hints | CLI/runtime and docs disagree about local vs provisioned auth | Auth and local mode |
| Webhook delivery blocked | Check WEBHOOK_ALLOWED_DOMAINS and webhook signing config | Destination domain and secret policy are present | Production destination policy or signing secret is missing | Webhooks and event delivery |
| Entitlement missing | npx spaps verify --json | Runtime/auth checks name the failing control | Payment state did not project to feature access | Billing and entitlements |
| Ready check reports PII failure | curl -fsS http://localhost:3301/health/ready | PII readiness check names the missing invariant | SPAPS_PII_MASTER_KEY is absent for PII-enabled apps | Security invariants |
| Pagefind or docs build failure | npm run build | Next build and Pagefind postbuild complete | Broken MDX, search output, or static build issue | Release governance |
make pytest reports no affected tests | make pytest | Testmon reports affected or no affected tests | No impacted tests were selected | Testing and TDD |
Debug Commands
curl -fsS http://localhost:3301/health | jq
curl -fsS http://localhost:3301/health/ready | jq
curl -fsS http://localhost:3301/health/local-mode | jq
make pytest
make lint
make typecheckCommon Mistakes
Do not fix a dependency-layer failure by weakening a domain service. The service may never be reached.
- Debugging an auth route with the wrong application key.
- Forgetting that local mode can still validate explicit real API keys.
- Updating frontend environment variables when the problem is an application database row.