What causes "[DATA_DIR] '${configured}' not writable → fallback ~/.${APP_NAME}" in decolua/9router?

Grant the running user write access: chown/chmod the DATA_DIR path (or icacls on Windows).

[DATA_DIR] '${configured}' not writable → fallback ~/.${APP_

Error message

[DATA_DIR] '${configured}' not writable → fallback ~/.${APP_NAME}

What it means

Warning from getDataDir() when the configured DATA_DIR cannot be created or written: fs.mkdirSync throws EACCES or EPERM. The function logs this and falls back to the default ~/.<APP_NAME> directory instead of crashing. Any other error code is rethrown.

Source

Thrown at src/lib/dataDir.js:30

}

export function getDataDir() {
  const configured = process.env.DATA_DIR;
  if (!configured) return defaultDir();

  // On Windows, ignore Unix-style absolute paths (e.g. /var/lib/...) that come
  // from a Linux-targeted .env or Docker config — they are not valid here.
  if (process.platform === "win32" && /^\//.test(configured)) {
    console.warn(`[DATA_DIR] '${configured}' is a Unix path on Windows → fallback to default`);
    return defaultDir();
  }

  try {
    fs.mkdirSync(configured, { recursive: true });
    return configured;
  } catch (e) {
    if (e?.code === "EACCES" || e?.code === "EPERM") {
      console.warn(`[DATA_DIR] '${configured}' not writable → fallback ~/.${APP_NAME}`);
      return defaultDir();
    }
    throw e;
  }
}

export const DATA_DIR = getDataDir();

View on GitHub (pinned to 90b52e06ff)

Solutions

Grant the running user write access: chown/chmod the DATA_DIR path (or icacls on Windows).
Change DATA_DIR to a user-writable location (e.g. ~/.9router/data or /opt/9router/data with correct ownership).
Remove DATA_DIR to accept the default fallback directory.
In Docker, mount a writable volume at DATA_DIR and ensure the container user owns it.

Example fix

// before (docker-compose.yml)
volumes: []  # container fs read-only
// after
volumes:
  - 9router-data:/data
environment:
  - DATA_DIR=/data

Defensive patterns

Strategy: validation

Validate before calling

import fs from "node:fs";
const d = process.env.DATA_DIR;
if (d) {
  try { fs.mkdirSync(d, { recursive: true }); fs.accessSync(d, fs.constants.W_OK); }
  catch (e) { console.warn(`DATA_DIR ${d} not writable (${e.code}) — fix permissions or unset DATA_DIR`); }
}

Prevention

Check writability of DATA_DIR with the same user that runs the app before launching.
In Docker, mount a writable volume and match ownership to the container user (chown).
Avoid system paths (/var/lib, C:\Program Files) unless the service account owns them.
Run a preflight check in your start script and fail fast with a clear message.

When it happens

Trigger: DATA_DIR points to a directory the process user cannot create or write: permission-protected path (e.g. /var/lib/... without root, C:\Program Files\...), read-only volume, sandboxed/container filesystem, or a parent dir owned by another user.

Common situations: Running the app as non-root with DATA_DIR under /var or /etc; Docker container with a read-only mount; systemd service with a hardened (ProtectSystem) unit; Windows service account lacking rights to the target folder.

Related errors

AI-assisted analysis of decolua/9router@90b52e06ff (2026-08-30). Data as JSON: /api/errors/852e40ed88a989fa. Report an issue: GitHub.