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.

Compiler stays on loading

The cloud gateway checks the compiler container with a five-second deadline. A container that is warming or does not answer reports status: "loading"; status: "ready" requires the compiler itself to report readiness. The CLI limits each health request to ten seconds and retries within a four-minute elapsed-time budget before reporting an error. These limits include response body reads, so a stalled connection cannot leave the CLI waiting indefinitely.

A successful container lifecycle check alone does not prove compilation works. After restarting or replacing an unhealthy instance, check /health and compile an example project. If HTTP remains unresponsive, inspect Cloudflare container logs and networking rather than repeatedly restarting the same instance. You can use the local Docker compiler while the hosted service is unavailable.

"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 build with --verbose for detailed output

Drizzle rename prompts in CI/headless compile

Run quickback build with the updated Quickback CLI. SQLite migration targets automatically select create for new tables and columns when their migration plan enables auto-create; explicit rename hints take precedence. The CLI handles repeated prompts without user input. PostgreSQL targets require rename hints.

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"]

If the CLI already selected create but generation still failed, inspect the end of the reported Drizzle output for the unfinished prompt or process error. A failed generate or postprocessor leaves existing migration history untouched. Do not use raw drizzle-kit generate as an equivalent workaround for an auth upgrade: it skips Quickback's OAuth client backfills and resource-grant cleanup.

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. The complete compile (complete=true — Generated Backend, or quickback compile) is the first time that command runs.

complete compile: wrangler bundle failed

The complete compile bundles the generated Worker with wrangler deploy --dry-run. A typical cause is a named import the generated define-action helper does not re-export:

No matching export in "src/features/tables/.quickback/define-action.ts" for import "reservations"

The helper re-exports every table in that feature only. If reservations is another table inside tables, import it from the action's own ../.quickback/define-action helper. If it belongs to a separate reservations feature, keep defineAction from the action's own feature and import only the external table from ../../reservations/.quickback/define-action (or the generated ../../reservations/reservations table module). Import query operators as q from project ../../../lib/q; neither feature helper owns them. This is the same rule for any waitlist/reservations-style cross-feature action: the local helper supplies the bound action context, and each external feature supplies its own tables.

Current compilers validate named imports from generated action helpers before code generation. Start's definition-validation build (complete=false) therefore rejects this source immediately with Invalid generated action-helper import(s) and names the owning feature, available table exports, and corrective import. If an older compiler or an already-generated project reaches Wrangler first, apply the same fix above and rebuild Generated Backend before Deploy.

The compile sandbox has no network and bundles against the compiler image's own dependencies, so anything you declare in build.dependencies is not installed there. Rather than fail on Could not resolve "yjs", the compiler skips the bundle check for those projects and says so in the compile warnings:

Skipped the Worker bundle check — build.dependencies not installed in the
compiler image: yjs, y-prosemirror

The compile still succeeds and the generated output is unchanged; unresolved imports and missing named exports surface at wrangler deploy instead.

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