bknd-troubleshoot_skill

Overview

This skill helps diagnose and fix common Bknd.io errors quickly. It organizes troubleshooting by error code, symptom, and frequent mistake patterns to get projects back online fast. Use it for quick reference, actionable fixes, and configuration checks when something in your Bknd project fails.

How this skill works

The skill inspects error messages, HTTP status codes, server logs, and common misconfigurations to recommend targeted fixes. It maps symptoms (like auth failures, 404s, or disappearing data) to concise commands, code snippets, and config changes you can apply immediately. It also provides diagnostic commands to verify server health, routes, schema, and auth state.

When to use it

• You see HTTP errors (400, 401, 403, 404, 409, 413, 500) from the Bknd API.
• Authentication or permission checks fail in browser or API clients.
• Data disappears after restart or uploads fail due to size/settings.
• You get configuration or runtime errors during development or deploy.
• You need fast, step-by-step fixes for common Bknd mistakes.

Best practices

• Check server logs first and reproduce with curl before debugging frontend.
• Keep entity names lowercase and restart server after schema changes.
• Persist tokens with storage (localStorage/sessionStorage) in Api config.
• Enable auth guard explicitly (enabled: true) when defining roles and permissions.
• Use file-based DB in production; avoid :memory: for persistent data.

Example use cases

• Fix 401 Unauthorized by verifying token storage, header format, or /me endpoint.
• Resolve 404 by listing routes, checking entity case, or re-syncing schema.
• Handle 409 duplicate errors by checking unique constraints before creating records.
• Stop data loss by switching from memory DB to file DB and updating run command.
• Troubleshoot CORS cookie issues by enabling credentials and correct sameSite/secure settings.