Debugging Common Issues

Diagnose and fix common Bknd problems using CLI tools, error analysis, and systematic troubleshooting.

Prerequisites

• Bknd project set up locally
• Terminal/command line access
• Basic understanding of HTTP status codes

When to Use UI Mode

• Inspecting data in admin panel (/admin)
• Verifying entity schema visually
• Testing CRUD operations manually
• Checking user/role configurations

When to Use Code Mode

• Running debug CLI commands
• Analyzing API response errors
• Checking route registration
• Inspecting configuration paths
• Reviewing server logs

CLI Debug Commands

Show All Registered Routes

npx bknd debug routes

Output shows every HTTP endpoint:

• API routes (/api/data/*, /api/auth/*, /api/media/*)
• Admin routes (/admin/*)
• Custom Flow HTTP triggers
• Plugin routes

Use when: endpoint returns 404, verifying custom routes registered.

Show Internal Paths

npx bknd debug paths

Output:

[PATHS] {
  rootpath: '/path/to/bknd',
  distPath: '/path/to/dist',
  relativeDistPath: './dist',
  cwd: '/your/project',
  dir: '/path/to/cli',
  resolvedPkg: '/path/to/package.json'
}

Use when: config file not loading, path resolution issues.

CLI Help

npx bknd --help
npx bknd run --help
npx bknd types --help

HTTP Error Codes

Common Issues & Solutions

Config File Not Loading

Symptoms: “Config file could not be resolved” error

Diagnose:

# Check config exists
ls bknd.config.*

# Check current directory
pwd

# Check what bknd sees
npx bknd debug paths

Solutions:

# Ensure correct extension
mv bknd.config.js bknd.config.ts

# Specify explicitly
npx bknd run -c ./bknd.config.ts

# Check supported extensions: .ts, .js, .mjs, .cjs, .json

Database Not Persisting

Symptoms: Data disappears on server restart

Diagnose:

# Check if using memory mode
# Look for "Using in-memory" in startup output
npx bknd run

# Check for database file
ls *.db

Solutions:

# Use file-based database
npx bknd run --db-url "file:data.db"

# NOT memory mode
npx bknd run --memory  # Data will be lost!

# Verify in config:
# connection: { url: "file:data.db" }  ✓
# connection: { url: ":memory:" }      ✗

Port Already in Use

Symptoms: EADDRINUSE: address already in use

Diagnose:

# Find process using port
lsof -i :3000

# Or on Windows
netstat -ano | findstr :3000

Solutions:

# Use different port
npx bknd run --port 3001

# Kill existing process
kill -9 <PID>

# Or on Windows
taskkill /PID <PID> /F

Authentication Not Working

Symptoms: 401 errors, token not persisting, user always null

Diagnose:

# Test login endpoint
curl -X POST http://localhost:3000/api/auth/password/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password"}'

# Check auth configuration
# Look for "strategy" in response errors

Solutions:

1. Auth not enabled:

export default {
  app: {
    auth: { enabled: true },  // Required!
  }
}

2. Wrong strategy path:

# Password auth endpoint:
POST /api/auth/password/login    # ✓
POST /api/auth/login             # ✗ 404

3. JWT secret not set (production):

auth: {
  jwt: {
    secret: process.env.JWT_SECRET,  // Required for production
  }
}

4. Cookie not set (CORS):

auth: {
  cookie: {
    secure: false,     // Set true only for HTTPS
    sameSite: "lax",   // Not "strict" for OAuth
  }
}

5. Token not persisting (frontend):

const api = new Api({
  host: "http://localhost:3000",
  storage: localStorage,  // Required for token persistence
});

Permission Denied (403)

Symptoms: Valid token but 403 Forbidden

Diagnose:

# Check user's role
curl http://localhost:3000/api/auth/me \
  -H "Authorization: Bearer <token>"

# Check role permissions in config

Solutions:

1. Guard not enabled:

export default {
  app: {
    auth: {
      guard: { enabled: true },  // Required for permissions
    }
  }
}

2. No default role (anonymous access):

auth: {
  guard: {
    roles: {
      anonymous: {
        is_default: true,  // Allow unauthenticated access
        permissions: ["data.entity.read"],
      }
    }
  }
}

3. Role missing permission:

roles: {
  user: {
    permissions: [
      "data.entity.read",
      "data.entity.create",  // Add if needed
    ]
  }
}

4. Entity-specific permission needed:

permissions: [
  { permission: "data.entity.read", entity: "posts" },
]

Entity/Record Not Found (404)

Symptoms: 404 on data endpoints

Diagnose:

# List all entities
curl http://localhost:3000/api/data

# Check entity name (case-sensitive)
curl http://localhost:3000/api/data/Posts    # ✗
curl http://localhost:3000/api/data/posts    # ✓

# Verify routes
npx bknd debug routes | grep data

Solutions:

1. Schema not synced:

# Restart server to sync schema
npx bknd run

2. Entity name case mismatch:

// Schema defines lowercase
entity("posts", { ... })

// API call must match exactly
api.data.readMany("posts");     // ✓
api.data.readMany("Posts");     // ✗ 404

3. Record doesn’t exist:

const result = await api.data.readOne("posts", 999);
if (!result.ok) {
  console.log("Not found:", result.status);  // 404
}

Type Errors with em()

Symptoms: TypeScript errors using schema object

Problem: em() returns schema definition, NOT queryable EntityManager.

// WRONG - this will fail
const schema = em({
  posts: entity("posts", { title: text() }),
});
schema.repo("posts").find();  // ✗ Error!

// CORRECT - use SDK for queries
const api = new Api({ url: "http://localhost:3000" });
await api.data.readMany("posts");  // ✓

For direct database access (server-side only):

const app = new App(config);
await app.build();
const posts = await app.em.repo("posts").findMany();  // ✓

Schema Sync Issues

Symptoms: Entity exists in code but not in database, or vice versa

Diagnose:

# Check admin panel -> Schema view
# Or query directly
curl http://localhost:3000/api/system/schema

Solutions:

1. Restart server – schema syncs on startup:

npx bknd run

2. Force sync (may drop data):

options: {
  sync: {
    force: true,  // Dangerous! Can drop tables
  }
}

3. Check mode – Database Mode ignores code schema:

// Code Mode (default) - schema from code
mode: "code"

// Hybrid Mode - merges code + database
mode: "hybrid"

File Upload Failing

Symptoms: 413 error, upload silently fails

Diagnose:

# Check file size
ls -la myfile.jpg

# Test upload
curl -X POST http://localhost:3000/api/media/upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@myfile.jpg"

Solutions:

1. File too large:

media: {
  body_max_size: 10 * 1024 * 1024,  // 10MB
}

2. Storage not configured:

media: {
  adapter: {
    type: "s3",
    // ... S3 config
  }
}

3. Local storage (dev only):

import { registerLocalMediaAdapter } from "bknd/adapter/node";
const local = registerLocalMediaAdapter();

export default {
  app: {
    media: { adapter: local }
  }
}

CORS Errors

Symptoms: “Access-Control-Allow-Origin” errors in browser console

Diagnose:

# Check CORS headers
curl -I http://localhost:3000/api/data/posts \
  -H "Origin: http://localhost:5173"

Solutions:

export default {
  app: {
    server: {
      cors: {
        origin: ["http://localhost:5173", "https://myapp.com"],
        credentials: true,  // For cookies
      }
    }
  }
}

For development (allow all):

server: {
  cors: {
    origin: "*",
  }
}

Headless Environment Crash

Symptoms: spawn xdg-open ENOENT on server without display

Solution:

npx bknd run --no-open

Windows ESM Errors

Symptoms: ERR_UNSUPPORTED_ESM_URL_SCHEME on Windows

Solutions:

1. Use Node.js 18+
2. Ensure "type": "module" in package.json
3. Use .mjs extension for config

TypeScript Types Not Updating

Symptoms: IDE shows old types, autocomplete wrong

Solutions:

# Regenerate types
npx bknd types

# Restart TypeScript server (VS Code)
# Cmd/Ctrl + Shift + P -> "TypeScript: Restart TS Server"

# Clear cache
rm -rf node_modules/.cache

Debug Script Pattern

Create a debug helper for systematic troubleshooting:

// debug.ts
import { Api } from "bknd/client";

async function debug() {
  const api = new Api({ host: "http://localhost:3000" });

  // 1. Check server health
  console.log("=== Health Check ===");
  const entities = await fetch("http://localhost:3000/api/data");
  console.log("Status:", entities.status);
  console.log("Entities:", await entities.json());

  // 2. Check auth
  console.log("\n=== Auth Check ===");
  const me = await api.auth.me();
  console.log("Auth status:", me.ok ? "authenticated" : "not authenticated");
  if (me.data) console.log("User:", me.data);

  // 3. Check schema
  console.log("\n=== Schema Check ===");
  const schema = await fetch("http://localhost:3000/api/system/schema");
  console.log("Schema:", await schema.json());

  // 4. Test entity access
  console.log("\n=== Entity Access ===");
  const posts = await api.data.readMany("posts", { limit: 1 });
  console.log("Posts access:", posts.ok ? "success" : `failed (${posts.status})`);
}

debug().catch(console.error);

Run with:

npx tsx debug.ts

Logging Patterns

Server-Side Logging

// In seed function or plugin
options: {
  seed: async (ctx) => {
    console.log("[SEED] Starting...");
    console.log("[SEED] Entities:", Object.keys(ctx.em.entities));

    try {
      await ctx.em.mutator("posts").insertOne({ title: "Test" });
      console.log("[SEED] Created post");
    } catch (e) {
      console.error("[SEED] Error:", e);
    }
  }
}

API Response Logging

const api = new Api({
  host: "http://localhost:3000",
  verbose: true,  // Logs all requests/responses
});

// Or manual logging
const result = await api.data.readMany("posts");
console.log("Request result:", {
  ok: result.ok,
  status: result.status,
  data: result.data,
  error: result.error,
});

Custom Fetcher with Logging

const api = new Api({
  host: "http://localhost:3000",
  fetcher: async (url, options) => {
    console.log("→", options?.method || "GET", url);
    const start = Date.now();
    const response = await fetch(url, options);
    console.log("←", response.status, `(${Date.now() - start}ms)`);
    return response;
  },
});

Flow/Task Debugging

HTTP Trigger Errors

Sync mode returns errors in response:

{
  "success": false,
  "errors": [
    {
      "task": "fetchUser",
      "error": "Failed to fetch user: 404 Not Found",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}

Task Error Handling

import { Task, Condition } from "bknd/flows";

const flow = new Flow("myFlow", [
  mainTask,
  errorTask.connect(mainTask, Condition.error()),  // Handle errors
]);

Verification Checklist

When debugging, check these in order:

1. Server running?

   curl http://localhost:3000/api/data
   

2. Config loaded?

   • Check startup logs for “Using config from”

3. Schema synced?

   • Check admin panel or /api/system/schema

4. Auth enabled? (if needed)

   • Check auth: { enabled: true } in config

5. Permissions set? (if 403)

   • Check guard: { enabled: true } and roles

6. CORS configured? (if browser errors)

   • Check server: { cors: {...} }

DOs and DON’Ts

DO:

• Check server logs first
• Use npx bknd debug routes for 404s
• Verify entity names match exactly (case-sensitive)
• Test with curl before debugging frontend
• Use verbose: true in Api for request logging
• Restart server after schema changes

DON’T:

• Assume em() returns a queryable EntityManager
• Forget --no-open on headless servers
• Use :memory: database for persistent data
• Skip checking HTTP status codes in responses
• Ignore CORS when debugging frontend issues
• Use sync: { force: true } in production

Related Skills

• bknd-local-setup – Initial project setup
• bknd-env-config – Environment variables
• bknd-setup-auth – Authentication configuration
• bknd-assign-permissions – Permission troubleshooting
• bknd-api-discovery – Explore available endpoints