---
title: "Troubleshooting"
description: "Common database logging failures in Blyp and how to fix them."
canonical_url: "https://www.blyp.dev/docs/database/troubleshooting"
markdown_url: "https://www.blyp.dev/docs/database/troubleshooting.md"
last_updated: "2018-10-20"
x_farming_labs_generated_preamble: true
agent:
  task: "Diagnose missing or failed Blyp database writes without losing existing log data."
  outcome: "The failing layer is identified as config loading, adapter wiring, schema drift, connectivity, or flushing."
  appliesTo:
    package:
      - "@blyp/core"
  prerequisites:
    - "Capture the startup error and preserve the current config"
    - "migration state"
    - "and database data."
  files:
    - "blyp.config.ts"
    - "prisma/schema.prisma"
    - "drizzle.config.ts"
  sideEffects:
    - "Repair migrations can alter production schema; inspect them before applying."
  verification:
    - "Emit a unique record"
    - "flush"
    - "and query it directly from the database."
  rollback:
    - "Revert only the repair change while leaving retained log data intact."
  failureModes:
    - symptom: "No useful error is visible."
      resolution: "Reproduce with startup diagnostics and a direct adapter connectivity check before changing schema."
---

# Troubleshooting
URL: /docs/database/troubleshooting
LLM index: /llms.txt
Description: Common database logging failures in Blyp and how to fix them.
Related: /docs/database, /docs/database/schema, /docs/database/migrations

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Diagnose missing or failed Blyp database writes without losing existing log data.
Outcome: The failing layer is identified as config loading, adapter wiring, schema drift, connectivity, or flushing.

### Applies To

- Package: `@blyp/core`

### Prerequisites

- Capture the startup error and preserve the current config
- migration state
- and database data.

### Files

- `blyp.config.ts`
- `prisma/schema.prisma`
- `drizzle.config.ts`

### Side Effects

- Repair migrations can alter production schema; inspect them before applying.

### Verification

- Emit a unique record
- flush
- and query it directly from the database.

### Rollback

- Revert only the repair change while leaving retained log data intact.

### Failure Modes

- No useful error is visible. — Recovery: Reproduce with startup diagnostics and a direct adapter connectivity check before changing schema.
<!-- farming-labs:agent-contract:end -->

# Troubleshooting

Preserve data and isolate the layer in order: executable config, adapter construction, database
connectivity, live schema, insert, then flush. Compare the live schema to `/docs/database/schema`.
Prove recovery with a uniquely named record queried directly from the database; avoid destructive
schema resets as a diagnostic shortcut.

Use this page when database mode is configured but logs are missing, inserts fail, or Blyp falls back to a disabled database state.

> **High-risk area:** Schema mismatches can make database logging effectively unusable. Treat the generated Blyp schema as a strict compatibility contract.

## `destination: "database"` is set, but database logging is silently disabled

Likely cause:
You are using `blyp.config.json` instead of an executable config file, so the adapter runtime object cannot be loaded.

Fix:
Move the config to `blyp.config.ts`, `blyp.config.mts`, `blyp.config.js`, or another executable `blyp.config.*` file and wire the adapter there.

## Database logging is disabled because the dialect is unsupported

Likely cause:
For a SQL-backed Prisma or Drizzle setup, `database.dialect` is not `postgres` or `mysql`.

Fix:
Use one of the supported SQL dialects and make sure it matches your ORM configuration. MongoDB through Mongoose does not require `database.dialect`.

## Database logging is enabled without an adapter

Likely cause:
`destination: "database"` is set but `database.adapter` is missing.

Fix:
Provide `createPrismaDatabaseAdapter({ client, model })`, `createDrizzleDatabaseAdapter({ db, table })`, or `createMongooseDatabaseAdapter({ mongoose, mongoUrl })`.

## Prisma delegate `blypLog` is missing

Likely cause:
The Prisma client does not expose the expected delegate, usually because the model is missing, renamed, or the generated client is stale.

Fix:
Make sure the Prisma model is `BlypLog`, mapped to `blyp_logs`, run migrations, then run `blyp db:generate`.

## Drizzle adapter fails because `db.insert` or the table reference is missing

Likely cause:
The adapter received the wrong DB object, the wrong table symbol, or an incomplete runtime stub.

Fix:
Pass the real Drizzle DB instance and the correct table symbol:

```ts
createDrizzleDatabaseAdapter({
  db,
  table: blypLogs,
});
```

## Mongoose adapter is configured but database logging is disabled

Likely cause:
The adapter is missing both a Mongoose object and an existing connection.

You may see this warning:

```txt
[Blyp] Warning: Mongoose adapter requires either a mongoUrl or an existing connection. Database logging is disabled.
```

Fix:
Pass a Mongoose module/object or an existing connection:

```ts
createMongooseDatabaseAdapter({
  mongoose,
  mongoUrl: process.env.MONGODB_URI,
});
```

## Mongoose is not installed

Likely cause:
The app config imports `mongoose`, but the package is missing from dependencies.

Fix:
Install Mongoose:

```bash
bun add mongoose
```

## MongoDB connection is missing or not ready

Likely cause:
`MONGODB_URI` is missing when using `mongoUrl`, or the existing Mongoose connection does not expose a native `db` instance yet.

Fix:
Set `MONGODB_URI` before starting the app, or wait until the existing Mongoose connection is open before passing it to Blyp.

## MongoDB logs are inserted but not visible in the expected collection

Likely cause:
The adapter is writing to a custom `collection` value while you are inspecting the default `blyp_logs` collection.

Fix:
Check the configured collection name:

```ts
createMongooseDatabaseAdapter({
  mongoose,
  mongoUrl: process.env.MONGODB_URI,
  collection: "blyp_logs",
});
```

## Migrations ran, but inserts still fail

Likely cause:
The database contains a table or model that looks similar to Blyp but does not match the actual contract.

Fix:
Compare the live schema against [Schema Contract](/docs/database/schema). Verify:

- the table is `blyp_logs`
- required columns exist
- JSON-capable columns exist
- required indexes exist
- the adapter points to the expected model or table symbol

## The adapter points to the wrong model or table symbol

Likely cause:
Prisma config uses a different delegate name, or Drizzle config points to a table other than `blypLogs`.

Fix:

- Prisma: use `model: "blypLog"` unless you have intentionally changed the Prisma delegate name in a compatible way
- Drizzle: pass `table: blypLogs`
- MongoDB: inspect the configured `collection`, which defaults to `blyp_logs`

## Logs are missing at request boundaries in callback-style servers

Likely cause:
The process or request path completes before the async database queue is flushed.

Fix:
Call:

```ts
await logger.flush();
```

at the boundary where you need a hard durability point. This matters most in callback-style servers such as Express, Fastify, and NestJS.

## `traceId` is visible in other Blyp outputs but not in the database schema

Likely cause:
The database schema or migration state is older than the current Blyp contract.

Fix:
Regenerate or update the Blyp database schema and migrations so the supported `traceId` column is present.

## Related docs

- [Database](/docs/database)
- [Schema Contract](/docs/database/schema)
- [Prisma](/docs/database/prisma)
- [Drizzle](/docs/database/drizzle)
- [MongoDB](/docs/database/mongodb)
- [Migrations](/docs/database/migrations)

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).