{"record":{"id":"f3f586b543e8061d","repo":"openclaw/openclaw","slug":"fs-sandbox-file-system-entries-must-be-an-array","errorCode":null,"errorMessage":"fs sandbox file system entries must be an array.","messagePattern":"fs sandbox file system entries must be an array\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"extensions/codex/src/app-server/sandbox-exec-server/fs-policy.ts","lineNumber":52,"sourceCode":"  const permissions = requireObject(sandbox.permissions, \"fs sandbox permissions\");\n  const permissionType = requireString(permissions.type, \"fs sandbox permissions type\");\n  if (permissionType === \"disabled\" || permissionType === \"external\") {\n    return { unrestricted: true, entries: [] };\n  }\n  if (permissionType !== \"managed\") {\n    throw new Error(`Unsupported Codex fs sandbox permission type: ${permissionType}`);\n  }\n\n  const fileSystem = requireObject(permissions.file_system, \"fs sandbox file system permissions\");\n  const fileSystemType = requireString(fileSystem.type, \"fs sandbox file system permissions type\");\n  if (fileSystemType === \"unrestricted\") {\n    return { unrestricted: true, entries: [] };\n  }\n  if (fileSystemType !== \"restricted\") {\n    throw new Error(`Unsupported Codex fs sandbox file system type: ${fileSystemType}`);\n  }\n  if (!Array.isArray(fileSystem.entries)) {\n    throw new Error(\"fs sandbox file system entries must be an array.\");\n  }\n  const cwd = readFsSandboxCwd(execServer, sandbox);\n  return {\n    unrestricted: false,\n    entries: fileSystem.entries.flatMap((entry, index) => {\n      const resolved = resolveFsSandboxEntry(\n        requireObject(entry, `fs sandbox entry ${index}`),\n        cwd,\n      );\n      return resolved ? [resolved] : [];\n    }),\n  };\n}\n\nfunction readFsSandboxCwd(execServer: OpenClawExecServer, sandbox: JsonObject): string {\n  if (sandbox.cwd === undefined || sandbox.cwd === null) {\n    return normalizeSandboxAbsolutePath(execServer.sandbox.containerWorkdir, \"sandbox cwd\");\n  }","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/openclaw/openclaw/blob/01804a75319da4b69c9ab98ceaa30477e22b8c0b/extensions/codex/src/app-server/sandbox-exec-server/fs-policy.ts#L34-L70","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide file_system.entries as a JSON array of entry objects","If your policy source is a map, convert it to an array before sending: Object.values(entriesMap)","Re-check the key name: a misspelled key leaves entries undefined and the real array ignored"],"exampleFix":"// before\n{ type: 'restricted', entries: { '/src': { access: 'read' } } }\n\n// after\n{ type: 'restricted', entries: [ { path: { type: 'path', path: '/src' }, access: 'read' } ] }","handlingStrategy":"validation","validationCode":"function assertEntriesArray(fileSystem: unknown): void {\n  if (!fileSystem || typeof fileSystem !== 'object' || !Array.isArray((fileSystem as any).entries)) {\n    throw new Error('file_system.entries must be an array');\n  }\n}","typeGuard":"function isEntriesArray(fileSystem: unknown): fileSystem is { entries: unknown[] } {\n  return !!fileSystem && typeof fileSystem === 'object' && Array.isArray((fileSystem as { entries?: unknown }).entries);\n}","tryCatchPattern":"try {\n  resolveFsSandboxPolicy(execServer, record);\n} catch (error) {\n  if (error instanceof Error && error.message.includes('entries must be an array')) {\n    // coerce a map to an array, or re-check the key name\n  } else throw error;\n}","preventionTips":["Serialize sandbox entries as a JSON array, never a map","Double-check the 'entries' key spelling in generated policy JSON"],"tags":["sandbox","codex","config","validation"],"backgroundTag":null,"analyzedSha":"01804a75319da4b69c9ab98ceaa30477e22b8c0b","analyzedAt":"2026-08-12T04:37:58.197Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}