lfnovo/open-notebook · error · HTTPException

Migration from environment variables failed

Error message

Migration from environment variables failed

What it means

Catch-all 500 from POST /api/credentials/migrate-from-env. This migration reads provider API keys from environment variables and creates credential records; failures reading env vars, or DB write errors during creation, produce this 500.

Source

Thrown at api/routers/credentials.py:500

    except Exception as e:
        logger.error(f"ProviderConfig migration FAILED: {type(e).__name__}: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail="Migration from provider config failed")


@router.post("/migrate-from-env")
async def migrate_from_env():
    """Migrate API keys from environment variables to credential records."""
    try:
        return await svc_migrate_from_env()
    except ValueError as e:
        raise _handle_value_error(e)
    except HTTPException:
        raise
    except OpenNotebookError:
        raise
    except Exception as e:
        logger.error(f"Env migration FAILED: {type(e).__name__}: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail="Migration from environment variables failed")

View on GitHub (pinned to a7de90d38a)

Solutions

1. Check logs for 'Env migration FAILED: <ExceptionType>: ...' with traceback
2. Verify OPEN_NOTEBOOK_ENCRYPTION_KEY and provider API key env vars are visible to the API process (not just your shell)
3. Ensure the DB is up and schema migrations ran (restart the API)
4. Retry the migration; existing provider env keys that already migrated are typically skipped or can be deduped after

// confirm env is visible to the API process before migrating
const status = await api.getEnvStatus(); // or verify env vars server-side
if (!status?.encryptionConfigured) throw new Error('Set OPEN_NOTEBOOK_ENCRYPTION_KEY before migrating');

try {
  await api.migrateFromEnv();
} catch (e) {
  if (e.status === 500) showError('Env migration failed — check API logs and required env vars');
  throw e;
}

When it happens

Trigger: Running migrate-from-env when the API process env lacks expected provider variables, when env var values are malformed, or when writing the resulting credential records fails (DB down, encryption key missing).

Common situations: OPEN_NOTEBOOK_ENCRYPTION_KEY unset so new credentials cannot be encrypted, migrating on a fresh install where DB schema hasn't been created yet, or env vars loaded inconsistently (shell vs docker-compose).

Related errors

• Failed to delete credential
• Migration from provider config failed
• Failed to check environment status
• Failed to list credentials
• Failed to list credentials for provider

AI-assisted analysis of lfnovo/open-notebook@a7de90d38a (2026-08-27). Data as JSON: /api/errors/076f976b2fb49e47. Report an issue: GitHub.