different-ai/openwork · error

The local managed MCP vault envelope is invalid.

Error message

The local managed MCP vault envelope is invalid.

What it means

readVaultFileState validates the parsed vault file against an expected shape (vault envelope, index, optional lastRecovery) and throws this plain Error when the file exists but does not match — the envelope is missing, mistyped, or the file is structurally corrupted/not JSON of the expected form.

Source

Thrown at apps/server/src/local-managed-mcp.ts:299

/** Parse the vault file without decrypting. Accepts v1 (bare envelope) and v2. */
async function readVaultFileState(config: ServerConfig): Promise<VaultFileState | null> {
  let raw: string;
  try {
    raw = await readFile(vaultPath(config), "utf8");
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
    throw error;
  }
  const value: unknown = JSON.parse(raw);
  if (isVaultEnvelope(value)) return { envelope: value, index: null, lastRecovery: null };
  if (isRecord(value) && value.schemaVersion === 2 && isVaultEnvelope(value.vault)) {
    return {
      envelope: value.vault,
      index: readVaultIndex(value.index),
      lastRecovery: isVaultRecovery(value.lastRecovery) ? value.lastRecovery : null,
    };
  }
  throw new Error("The local managed MCP vault envelope is invalid.");
}

function decryptVault(envelope: VaultEnvelope, key: Buffer): LocalManagedMcpVault {
  const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(envelope.iv, "base64"));
  decipher.setAAD(VAULT_AAD);
  decipher.setAuthTag(Buffer.from(envelope.tag, "base64"));
  const plaintext = Buffer.concat([
    decipher.update(Buffer.from(envelope.data, "base64")),
    decipher.final(),
  ]).toString("utf8");
  const value: unknown = JSON.parse(plaintext);
  if (!isVault(value)) throw new Error("The local managed MCP vault payload is invalid.");
  return value;
}

function vaultIndexEntry(connection: StoredLocalManagedMcpConnection): LocalManagedMcpIndexEntry {
  return {
    id: connection.id,

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Delete or restore the corrupted vault file and re-initialize the vault (credentials stored inside will need re-entry)
2. Restore the vault file from backup along with its recovery key
3. Check that the configured vault path points at the real vault file
4. Verify app versions match if the vault was produced by a different release (schema drift)
5. Recover via the vault's lastRecovery/key material if available, then re-seal

Example fix

// before (manual inspection corrupts file)
fs.writeFileSync(vaultPath, JSON.stringify({ some: "data" }));
// after
// restore valid shape: { vault: { iv, data, tag }, index: [...], lastRecovery: null }
fs.writeFileSync(vaultPath, JSON.stringify({ vault: envelope, index: [], lastRecovery: null }));

function vaultFileLooksValid(content: string): boolean {
  try {
    const v = JSON.parse(content);
    return !!v?.vault && typeof v.vault.iv === "string" && typeof v.vault.data === "string" && typeof v.vault.tag === "string" && Array.isArray(v.index);
  } catch { return false; }
}

function isVaultEnvelopeShape(v: unknown): v is { vault: { iv: string; data: string; tag: string }; index: unknown[]; lastRecovery: unknown } {
  const o = v as Record<string, unknown> | null;
  const vault = o?.vault as Record<string, unknown> | undefined;
  return !!o && !!vault && typeof vault.iv === "string" && typeof vault.data === "string" && typeof vault.tag === "string" && Array.isArray(o.index);
}

try {
  const state = inspectLocalManagedMcpVault(path);
} catch (error) {
  if (error.message === "The local managed MCP vault envelope is invalid.") {
    // restore from backup or re-initialize the vault; do not overwrite blindly
  }
  throw error;
}

When it happens

Trigger: inspectLocalManagedMcpVault or loadVaultLocked (via file/inspect) reads a vault file whose JSON lacks a valid `vault` envelope or whose `index` is malformed, or reads a file written by an incompatible version.

Common situations: Vault file manually edited or truncated; partial write due to crash/disk-full; vault created by an older/newer schema version; wrong vault path pointing at an unrelated JSON file; test fixture reused incorrectly.

Related errors

• The local managed MCP vault payload is invalid.
• invalid_session_payload
• invalid_app_version_payload
• invalid_resource_snapshot_payload
• invalid_mcp_token_payload

AI-assisted analysis of different-ai/openwork@2b7df46e8a (2026-09-01). Data as JSON: /api/errors/2e806ad5e9322994. Report an issue: GitHub.