coleam00/Archon · error

Pi shim setup failed at ${shimDir}: ${err.message}

Error message

Pi shim setup failed at ${shimDir}: ${err.message}

What it means

ensurePiPackageDirShim sets up a Pi package-directory shim on the filesystem (env PI_PACKAGE_DIR points at it). Any fs failure (permission, disk space, etc.) is caught and rethrown as a classified error so the executor's catch sees a known shape instead of a raw errno error.

Source

Thrown at packages/providers/src/community/pi/provider.ts:116

  const shimPkgJson = join(shimDir, 'package.json');
  if (!existsSync(shimPkgJson)) {
    // `piConfig: {}` is explicit so Pi's defaults (`name: 'pi'`,
    // `configDir: '.pi'`) kick in — matches Pi's standalone behavior.
    try {
      mkdirSync(shimDir, { recursive: true });
      writeFileSync(
        shimPkgJson,
        JSON.stringify({
          name: 'archon-pi-shim',
          version: '0.0.0',
          piConfig: {},
        })
      );
    } catch (error) {
      // Surface as a classified error so the executor's catch sees a known
      // shape instead of a raw EACCES/ENOSPC from node:fs.
      const err = error as NodeJS.ErrnoException;
      throw new Error(`Pi shim setup failed at ${shimDir}: ${err.message}`);
    }
  }
  process.env.PI_PACKAGE_DIR = shimDir;
}

// ─── Bedrock backend registration (compiled-binary parity) ───────────────────

/**
 * Registrar for Pi's Bedrock backend module. Split out from
 * `ensureBedrockProviderRegistered` so tests can inject a spy without touching
 * the real SDK (Bun's `mock.module` is process-global and irreversible).
 */
export type BedrockRegistrar = () => Promise<void>;

/**
 * The default registrar: dynamically import the Pi SDK's Bedrock override hook
 * and the statically-bundled Bedrock module, then wire them together.
 *

View on GitHub (pinned to 0773b97458)

Solutions

1. Check permissions on the shim path (the path is in the message) and chown/chmod it
2. Free disk space if ENOSPC
3. Remove the stale/corrupt shim directory and re-run
4. Run under a user that owns the Pi agent directory (~/.pi)

Example fix

// before (run as unrelated user, dir owned by root)
$ archon run workflow
// after
$ sudo chown -R $(whoami) ~/.pi
$ archon run workflow

import { accessSync, constants } from 'node:fs';
try {
  accessSync(shimParent, constants.W_OK);
} catch {
  throw new Error(`Cannot write Pi shim dir at ${shimParent}: check permissions/disk space`);
}

function isFsErrnoException(e: unknown): e is NodeJS.ErrnoException {
  return e instanceof Error && typeof (e as NodeJS.ErrnoException).code === 'string';
}

try {
  await sendQuery(req);
} catch (err) {
  if (err.message.startsWith('Pi shim setup failed')) {
    const m = err.message.match(/: (\w+):/); // extract errno e.g. EACCES/ENOSPC
    console.error(`Fix filesystem at shim path (${m?.[1]}), then retry`);
  }
  throw err;
}

When it happens

Trigger: listPiModels or sendQuery invoking ensurePiPackageDirShim when the shim directory cannot be created/written: EACCES (read-only or non-owned path), ENOSPC (full disk), ENOENT on a parent path, or EEXIST with conflicting file type.

Common situations: Running the engine as a different user than a previous run (root-owned ~/.pi or cache dir), read-only containers, full disks in CI, or a file existing where the shim dir is expected.

Related errors

• EACCES
• Error loading workflows: ${err.message} Hint: Check permissi
• Detached run control directory is owned by another user: ${d
• Detached run control directory must have mode 0700: ${direct
• Cannot access command file at ${path}: ${err.message}

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/10d34e2367dd225a. Report an issue: GitHub.