{"record":{"id":"9b238ca8d1d76fd0","repo":"coleam00/Archon","slug":"error-loading-workflows-err-message-hint-chec","errorCode":null,"errorMessage":"Error loading workflows: ${err.message}\nHint: Check permissions on .archon/workflows/ directory.","messagePattern":"Error loading workflows: (.+?)\nHint: Check permissions on \\.archon/workflows/ directory\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/workflow.ts","lineNumber":1042,"sourceCode":"  }\n}\n\n/**\n * Load workflows from the DISCOVERY root with standardized error handling.\n *\n * The root passed here owns both the workflow files and the `defaults:` /\n * `commands.folder` settings that govern how they are discovered — a workflow's own\n * checkout decides which command folder its command nodes name. What the run then DOES\n * is governed separately by the target's config, loaded inside `executeWorkflow`.\n */\nasync function loadWorkflows(cwd: string): Promise<WorkflowLoadResult> {\n  try {\n    // Home-scoped workflows at ~/.archon/workflows/ are discovered automatically —\n    // no option needed since the discovery helper reads them unconditionally.\n    return await discoverWorkflowsWithConfig(cwd, loadConfig);\n  } catch (error) {\n    const err = error as Error;\n    throw new Error(\n      `Error loading workflows: ${err.message}\\nHint: Check permissions on .archon/workflows/ directory.`\n    );\n  }\n}\n\n/**\n * Print a workflow's parse warnings (keys the engine silently drops) to stderr.\n *\n * stderr rather than stdout so `--json` callers keep a parseable payload while\n * still being told; `console.warn` rather than the logger because `--json` sets\n * the log level to silent, which is exactly the case this has to survive.\n */\nexport function emitParseWarnings(\n  parseWarnings: readonly string[] | undefined,\n  workflowName: string\n): void {\n  if (!parseWarnings || parseWarnings.length === 0) return;\n  console.warn(`Warning: '${workflowName}' declares keys the engine ignores:`);","sourceCodeStart":1024,"sourceCodeEnd":1060,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/cli/src/commands/workflow.ts#L1024-L1060","documentation":"loadWorkflows() wraps discoverWorkflowsWithConfig (which also unconditionally scans ~/.archon/workflows/) so any failure during workflow discovery/load becomes a uniform 'Error loading workflows' message with the original error text and a permissions hint. It indicates the CLI could not enumerate or read workflow files from the discovery directories.","triggerScenarios":"discoverWorkflowsWithConfig throws because .archon/workflows/ or ~/.archon/workflows/ is unreadable (EACCES), the directory does not exist in an unexpected way, a workflow YAML file is unreadable, or the config loader (loadConfig) itself throws during discovery.","commonSituations":"Workflow files created by root while the CLI runs as another user; restrictive umask after copying workflow packs; a symlink to an unreadable location; HOME changed so ~/.archon/workflows points somewhere odd; corrupted YAML triggering a load error surfaced through this path.","solutions":["Check permissions on .archon/workflows/ and ~/.archon/workflows/ (`ls -la`) and ensure the running user can read them.","Read the embedded err.message — it names the specific file or directory that failed.","Fix ownership (`sudo chown -R $USER .archon/workflows`) if files were created by another user.","Remove or fix the offending workflow YAML file flagged in the message.","Verify HOME is set correctly if home-scoped discovery is failing."],"exampleFix":"// before: root-owned workflow dir\n$ ls -la .archon/workflows\ndrwx------ root root\n$ archon workflow run foo\nError loading workflows: EACCES: permission denied ...\n// after\n$ sudo chown -R $USER .archon/workflows && chmod -R u+rwX .archon/workflows","handlingStrategy":"validation","validationCode":"import { accessSync, constants, readdirSync } from 'fs';\nfor (const dir of ['.archon/workflows', `${process.env.HOME}/.archon/workflows`]) {\n  try {\n    accessSync(dir, constants.R_OK);\n    readdirSync(dir);\n  } catch {\n    console.warn(`Workflow directory not readable: ${dir}`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runWorkflow(name, opts);\n} catch (e) {\n  if (String((e as Error).message).startsWith('Error loading workflows')) {\n    console.error('Check permissions on .archon/workflows/ and ~/.archon/workflows/:', (e as Error).message);\n  }\n}","preventionTips":["Keep .archon/workflows/ owned by the user running the CLI (avoid sudo-created files).","Use sane umasks when copying workflow packs; verify with `ls -la`.","Run a discovery pre-check after installing new workflow files.","Keep HOME set consistently between shells, services, and cron."],"tags":["filesystem","permissions","workflows","cli"],"backgroundTag":"permission-denied","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}