mastra-ai/mastra · error

wrapWithWriteLock: input.path is required

Error message

wrapWithWriteLock: input.path is required

What it means

The write-lock wrapper serializes mutating tool calls per file path via `writeLock.withLock(input.path, ...)`. If the wrapped tool is invoked without `input.path`, the lock cannot be keyed and the wrapper throws 'wrapWithWriteLock: input.path is required'. This is an internal precondition check, not a domain error class.

Source

Thrown at packages/core/src/workspace/tools/tools.ts:371

      try {
        output = await tool.execute(input, context);
      } catch (error) {
        await hooks.afterToolCall?.({ ...hookContext, output, error });
        throw error;
      }

      await hooks.afterToolCall?.({ ...hookContext, output });
      return output;
    },
  };
}

function wrapWithWriteLock(tool: any, writeLock: FileWriteLock): any {
  return {
    ...tool,
    execute: async (input: any, context: any = {}) => {
      if (!input.path) {
        throw new Error('wrapWithWriteLock: input.path is required');
      }
      return writeLock.withLock(input.path, () => tool.execute(input, context));
    },
  };
}

// ---------------------------------------------------------------------------
// Factory
// ---------------------------------------------------------------------------

/**
 * Creates workspace tools that will be auto-injected into agents.
 *
 * @param workspace - The workspace instance to bind tools to
 * @returns Record of workspace tools
 */
export async function createWorkspaceTools(
  workspace: Workspace,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure the tool call input includes a `path` property with a string value
2. If your tool uses a different input key, rename it to `path` in the tool's input schema or map it before wrapping
3. Validate tool input against the schema (Zod parse) before calling execute so missing path is caught with a clearer validation message

Example fix

// before
await tool.execute({ filePath: 'a.txt' }, ctx); // throws

// after
await tool.execute({ path: 'a.txt' }, ctx);

if (typeof input?.path !== 'string' || input.path.length === 0) {
  throw new Error('Tool input must include a non-empty string `path`.');
}

function hasPath(input) {
  return typeof input === 'object' && input !== null && typeof input.path === 'string' && input.path.length > 0;
}

try {
  return await tool.execute(input, ctx);
} catch (err) {
  if (err instanceof Error && err.message.includes('input.path is required')) {
    return { error: 'Malformed tool call: missing `path` in input.' };
  }
  throw err;
}

When it happens

Trigger: Invoking a write-locked tool with input missing the `path` field — e.g. the model emits a malformed tool call with no path, a custom tool is wrapped but its input schema uses a different key (like `filePath` or `file`), or execute is called programmatically with an empty/partial input object.

Common situations: Custom tools registered through `addTool` whose input schema names the path property something other than `path`; direct programmatic `execute` calls in tests skipping validation; model hallucinating a tool signature without path.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Unknown content type: ${(content as any).type}
• Factory rule version is required.
• Missing authorization code
• Input data not found
• Forecast data not found

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/b3af3cabc115647a. Report an issue: GitHub.