openclaw/openclaw · error · Error

fs sandbox file system entries must be an array.

Error message

fs sandbox file system entries must be an array.

What it means

When file_system.type is 'restricted', resolveFsSandboxPolicy requires file_system.entries to be an Array. A non-array (object, string, number, null-after-check) is rejected before any entry resolution runs, preventing partial or misread access lists.

Source

Thrown at extensions/codex/src/app-server/sandbox-exec-server/fs-policy.ts:52

  const permissions = requireObject(sandbox.permissions, "fs sandbox permissions");
  const permissionType = requireString(permissions.type, "fs sandbox permissions type");
  if (permissionType === "disabled" || permissionType === "external") {
    return { unrestricted: true, entries: [] };
  }
  if (permissionType !== "managed") {
    throw new Error(`Unsupported Codex fs sandbox permission type: ${permissionType}`);
  }

  const fileSystem = requireObject(permissions.file_system, "fs sandbox file system permissions");
  const fileSystemType = requireString(fileSystem.type, "fs sandbox file system permissions type");
  if (fileSystemType === "unrestricted") {
    return { unrestricted: true, entries: [] };
  }
  if (fileSystemType !== "restricted") {
    throw new Error(`Unsupported Codex fs sandbox file system type: ${fileSystemType}`);
  }
  if (!Array.isArray(fileSystem.entries)) {
    throw new Error("fs sandbox file system entries must be an array.");
  }
  const cwd = readFsSandboxCwd(execServer, sandbox);
  return {
    unrestricted: false,
    entries: fileSystem.entries.flatMap((entry, index) => {
      const resolved = resolveFsSandboxEntry(
        requireObject(entry, `fs sandbox entry ${index}`),
        cwd,
      );
      return resolved ? [resolved] : [];
    }),
  };
}

function readFsSandboxCwd(execServer: OpenClawExecServer, sandbox: JsonObject): string {
  if (sandbox.cwd === undefined || sandbox.cwd === null) {
    return normalizeSandboxAbsolutePath(execServer.sandbox.containerWorkdir, "sandbox cwd");
  }

View on GitHub (pinned to 01804a7531)

Solutions

  1. Provide file_system.entries as a JSON array of entry objects
  2. If your policy source is a map, convert it to an array before sending: Object.values(entriesMap)
  3. Re-check the key name: a misspelled key leaves entries undefined and the real array ignored

Example fix

// before
{ type: 'restricted', entries: { '/src': { access: 'read' } } }

// after
{ type: 'restricted', entries: [ { path: { type: 'path', path: '/src' }, access: 'read' } ] }
Defensive patterns

Strategy: validation

Validate before calling

function assertEntriesArray(fileSystem: unknown): void {
  if (!fileSystem || typeof fileSystem !== 'object' || !Array.isArray((fileSystem as any).entries)) {
    throw new Error('file_system.entries must be an array');
  }
}

Type guard

function isEntriesArray(fileSystem: unknown): fileSystem is { entries: unknown[] } {
  return !!fileSystem && typeof fileSystem === 'object' && Array.isArray((fileSystem as { entries?: unknown }).entries);
}

Try / catch

try {
  resolveFsSandboxPolicy(execServer, record);
} catch (error) {
  if (error instanceof Error && error.message.includes('entries must be an array')) {
    // coerce a map to an array, or re-check the key name
  } else throw error;
}

Prevention

When it happens

Trigger: A restricted policy where entries is an object map keyed by path, a comma-separated string, a single entry object, or absent-but-not-undefined. requireObject on file_system passes, but Array.isArray(fileSystem.entries) is false.

Common situations: Adapters that serialize an entries map instead of a list; config tooling that drops the array under a different key; hand-written policy JSON using '{}' where '[]' was intended.

Related errors

AI-assisted analysis of openclaw/openclaw@01804a7531 (2026-08-12). Data as JSON: /api/errors/f3f586b543e8061d. Report an issue: GitHub.