Troubleshooting

401 Unauthorized

Your session may have expired (sessions last 7 days). Re-authenticate:

quickback logout
quickback login

Compilation timeout

Large projects may take longer to compile. The cloud compiler uses Cloudflare Containers to run compilation in isolated environments. If you hit timeouts, try running the compiler locally.

"Command not found: quickback"

Make sure the CLI is installed globally:

npm install -g @quickback-dev/cli

Or use npx:

npx @quickback-dev/cli create cloudflare my-app

Compile errors

1. Check your quickback.config.ts exists and is valid
2. Ensure all tables in quickback/features/ have valid exports
3. Run quickback compile with --verbose for detailed output

Drizzle rename prompts in CI/headless compile

If compilation fails with an interactive Drizzle message like:

• drizzle-kit requested interactive rename input, but Quickback compile is running headless
• Missing rename hint for table/column ...

then add explicit rename hints in quickback.config.ts:

export default defineConfig({
  // ...
  compiler: {
    migrations: {
      renames: {
        tables: {
          events_v2: "events",
        },
        columns: {
          events: {
            summary_text: "summary",
          },
        },
      },
    },
  },
});

tables and columns mappings are always new_name -> old_name.

If a hint is missing, compile now fails loudly with the exact key path to add, for example:

• Expected hint key: compiler.migrations.renames.tables["events_v2"]
• Expected hint key: compiler.migrations.renames.columns["events"]["summary_text"]

Critical command failed: Generate features database migrations

drizzle-kit could not load the generated features schema. The usual cause on D1 (splitDatabases: true) is a feature column that .references() a Better Auth table:

userId: q.text().required().references(() => users.id, { onDelete: 'cascade' }) // illegal

users / user / organization / member live in AUTH_DB. Features live in DB. SQLite cannot FK across them, and drizzle-kit cannot resolve users when generating features migrations.

A Start chat compile (complete=false) still succeeds — it never runs drizzle-kit. Deploy (complete=true) is the first time that command runs.

Store the Better Auth id as plain text:

userId: q.text().required()

.references() is only for another feature table in DB. See Schema → References.

"Could not load organizations"

This can happen if your session token expired or if the API is temporarily unavailable. Re-login:

quickback logout
quickback login