BigPizzaV3/CodexPlusPlus · error

sidebar catalog entry is missing db_path

Error message

sidebar catalog entry is missing db_path

What it means

Each sidebar catalog entry must specify which SQLite database file it targets via a string "db_path" field. Without it the restore cannot locate the database and aborts. The path is later canonicalized and checked against allowed Codex databases.

Solutions

1. Add "db_path": "<absolute path to the codex sqlite db>" to the entry
2. Point db_path at a real Codex database under the codex home (it must canonicalize to an allowed path)
3. Re-export the snapshot so db_path is filled in
4. If the path was stripped for sharing, restore it to the local machine's actual database location

Example fix

// before
{ "table": "thread_catalog", "rows": [ ... ] }
// after
{ "table": "thread_catalog", "db_path": "/home/user/.codex/sessions.sqlite", "rows": [ ... ] }

for (const e of snapshot.catalog ?? []) {
  if (typeof e?.db_path !== 'string' || e.db_path.trim() === '') {
    throw new Error('catalog entry missing db_path');
  }
  if (!fs.existsSync(e.db_path)) throw new Error('db_path does not exist locally');
}

function entryHasDbPath(e) {
  return typeof e === 'object' && e !== null && typeof e.db_path === 'string' && e.db_path.trim() !== '';
}

try {
  restore_sidebar_snapshot(&snapshot, codex_home)?;
} catch (e) {
  if (String(e).includes('missing db_path')) {
    rewriteDbPathsToLocalCodexHome(snapshot); // re-point entries, then retry
  }
}

When it happens

Trigger: A catalog entry with no "db_path" key, or a non-string value (number/object/null), passed to the sidebar snapshot restore function.

Common situations: Hand-edited snapshot missing the path; exporter version change; entries copied between snapshots with the path stripped for privacy and not re-added; relative path stored where a resolvable path is needed.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• sidebar catalog entry is missing table
• sidebar catalog entry rows must be an array
• sidebar catalog row is missing thread_id
• catalog JSON 解析失败：
• sidebar snapshot catalog must be an array

AI-assisted analysis of BigPizzaV3/CodexPlusPlus@b1ed92e5e4 (2026-09-19). Data as JSON: /api/errors/ae02ca7c2d2894a7. Report an issue: GitHub.

Appendix: source

Thrown at crates/codex-plus-data/src/provider_sync.rs:2715

        .ok_or_else(|| anyhow::anyhow!("sidebar snapshot is missing thread_id"))?;
    if let Some(catalog) = snapshot.get("catalog") {
        let entries = catalog
            .as_array()
            .ok_or_else(|| anyhow::anyhow!("sidebar snapshot catalog must be an array"))?;
        let allowed_paths = sidebar_catalog_db_paths(codex_home)?;
        for entry in entries {
            let table = entry
                .get("table")
                .and_then(Value::as_str)
                .ok_or_else(|| anyhow::anyhow!("sidebar catalog entry is missing table"))?;
            if !SIDEBAR_CATALOG_TABLES.contains(&table) {
                anyhow::bail!("unsupported sidebar catalog table: {table}");
            }
            let path = entry
                .get("db_path")
                .and_then(Value::as_str)
                .map(PathBuf::from)
                .ok_or_else(|| anyhow::anyhow!("sidebar catalog entry is missing db_path"))?;
            let canonical = fs::canonicalize(&path)?;
            if !allowed_paths.contains(&canonical) {
                anyhow::bail!("sidebar catalog database is not an allowed Codex database");
            }
            let rows = entry
                .get("rows")
                .and_then(Value::as_array)
                .ok_or_else(|| anyhow::anyhow!("sidebar catalog entry rows must be an array"))?;
            for row in rows {
                let row_id = row
                    .get("thread_id")
                    .and_then(Value::as_str)
                    .ok_or_else(|| anyhow::anyhow!("sidebar catalog row is missing thread_id"))?;
                if row_id != thread_id {
                    anyhow::bail!("sidebar catalog row thread_id does not match snapshot");
                }
            }
        }

View on GitHub (pinned to b1ed92e5e4)