# Troubleshooting

## 401 Unauthorized

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

```bash
quickback logout
quickback login
```

## Compilation timeout

Large projects may take longer to compile. The cloud compiler uses [Cloudflare Containers](https://developers.cloudflare.com/containers/) to run compilation in isolated environments. If you hit timeouts, try [running the compiler locally](/tooling/cloud-compiler/local-compiler).

## "Command not found: quickback"

Make sure the CLI is installed globally:
```bash
npm install -g @quickback-dev/cli
```

Or use npx:
```bash
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`:

```typescript
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:

{/* doc-compile: skip — illegal one-liner, not a host feature */}
```typescript
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:

{/* doc-compile: skip — one-liner, not a host feature */}
```typescript
userId: q.text().required()
```

`.references()` is only for another feature table in `DB`. See
[Schema → References](/define/schema).

## "Could not load organizations"

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