nexu-io/open-design · critical · Error

OD_DATA_DIR is required when OD_SANDBOX_MODE is enabled

Error message

OD_DATA_DIR is required when OD_SANDBOX_MODE is enabled

What it means

Thrown by resolveDataDir() when OD_DATA_DIR is empty/unset AND options.requireExplicit is true. requireExplicit is set when OD_SANDBOX_MODE is enabled: sandbox mode restricts the daemon to an explicit data root, so silently defaulting to <projectRoot>/.od would defeat the sandbox boundary. The message names exactly which env var combination is at fault.

Source

Thrown at apps/daemon/src/daemon-paths.ts:133

    resourceRoot ?? null,
    path.join('data', 'plugin-previews'),
    path.join(projectRoot, 'data', 'plugin-previews'),
  );
}

export interface ResolveDataDirOptions {
  requireExplicit?: boolean;
}

export function resolveDataDir(
  raw: string | undefined,
  projectRoot: string,
  options: ResolveDataDirOptions = {},
): string {
  const value = raw?.trim();
  if (!value) {
    if (options.requireExplicit) {
      throw new Error('OD_DATA_DIR is required when OD_SANDBOX_MODE is enabled');
    }
    return path.join(projectRoot, '.od');
  }

  const resolved = resolveProjectRelativePath(value, projectRoot);
  try {
    fs.mkdirSync(resolved, { recursive: true });
    fs.accessSync(resolved, fs.constants.W_OK);
  } catch (err) {
    const e = err as Error;
    const currentUser = (() => {
      try {
        return os.userInfo().username;
      } catch {
        return process.env.USER ?? process.env.LOGNAME ?? 'unknown';
      }
    })();
    const parentDir = path.dirname(resolved);

View on GitHub (pinned to 5be4028344)

Solutions

1. Set OD_DATA_DIR to an explicit absolute path before starting the daemon in sandbox mode.
2. Disable OD_SANDBOX_MODE if sandbox isolation is not required (then the <projectRoot>/.od default applies).
3. Ensure the deployment manifest always pairs OD_SANDBOX_MODE with an OD_DATA_DIR volume.

Example fix

# before: sandbox on, no data dir
export OD_SANDBOX_MODE=1
# OD_DATA_DIR unset

# after: pair sandbox with an explicit data dir
export OD_SANDBOX_MODE=1
export OD_DATA_DIR=/var/lib/open-design

if (process.env.OD_SANDBOX_MODE && !process.env.OD_DATA_DIR?.trim()) {
  throw new Error('OD_DATA_DIR is required when OD_SANDBOX_MODE is enabled');
}

function sandboxConfigured(env: NodeJS.ProcessEnv): boolean {
  return ['1','true','yes'].includes((env.OD_SANDBOX_MODE ?? '').trim().toLowerCase());
}

try { resolveDataDir(process.env.OD_DATA_DIR, projectRoot, { requireExplicit: sandbox }); }
catch (e) {
  if (e instanceof Error && /OD_DATA_DIR is required/.test(e.message)) {
    // fail boot with a clear message: provision OD_DATA_DIR
  } else throw e;
}

When it happens

Trigger: Starting the daemon with OD_SANDBOX_MODE enabled but OD_DATA_DIR not provided (or only whitespace). resolveDataDir is called with requireExplicit=true in that mode.

Common situations: A packaged/sandboxed deployment forgot to provision OD_DATA_DIR; sandbox mode was turned on for testing without also pointing OD_DATA_DIR at the sandbox volume; whitespace-only value passed env-var presence checks but trimmed to empty.

Related errors

• ${RESOURCE_ROOT_ENV} must be under the workspace root or app
• OD_DATA_DIR "${resolved}" is not writable: ${e.message} Curr
• OD_CRITIQUE_SCORE_THRESHOLD (${scoreThreshold}) must be <= O
• ${key} must be a positive integer, got "${raw}"
• ${key} must be a non-negative finite number, got "${raw}"

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/01af687e7ebaaf59. Report an issue: GitHub.