can1357/oh-my-pi · error · ToolError

Invalid args for ${XD_URL_PREFIX}${device.name}: ${message}\

Error message

Invalid args for ${XD_URL_PREFIX}${device.name}: ${message}\n\n${docs()}

What it means

After parsing the JSON object, parseDeviceArgs validates it against the device's parameter schema via the wrapped tool. Any validation error thrown there is re-thrown as a single ToolError prefixed `Invalid args for xd://<device>` followed by the underlying message and the device's full docs, so the agent gets actionable schema guidance.

Source

Thrown at packages/coding-agent/src/tools/xdev.ts:181

	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
		throw new ToolError(
			`${XD_URL_PREFIX}${device.name} content must be a JSON object, got ${Array.isArray(parsed) ? "array" : typeof parsed}.`,
		);
	}
	// The harness only injects the intent field into top-level schemas; strip a
	// habitual `i` from inner args unless the wrapped schema really declares it.
	const args: Record<string, unknown> = { ...(parsed as Record<string, unknown>) };
	if ("i" in args && !schemaDeclaresIntentField(toolWireSchema(device))) delete args.i;
	try {
		return validateToolArguments(device, {
			type: "toolCall",
			id: toolCallId,
			name: device.name,
			arguments: args,
		});
	} catch (error) {
		const message = error instanceof Error ? error.message : String(error);
		throw new ToolError(`Invalid args for ${XD_URL_PREFIX}${device.name}: ${message}\n\n${docs()}`);
	}
}

/** One-line catalog summary for a mounted tool: `summary`, else first description line. */
function toolSummary(inst: Tool): string {
	if (inst.summary) return inst.summary;
	const firstLine = (inst.description ?? "").split("\n").find(line => line.trim().length > 0);
	return firstLine?.trim() ?? inst.label ?? inst.name;
}

/** C0/C1 controls and Unicode line/paragraph separators; summaries must remain one line. */
const SUMMARY_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g;
const SUMMARY_ELLIPSIS = "…";
const SUMMARY_ELLIPSIS_BYTES = Buffer.byteLength(SUMMARY_ELLIPSIS, "utf-8");

/**
 * Bound a catalog summary for prompt rendering. External summaries are
 * third-party metadata inlined verbatim, so control characters are stripped

View on GitHub (pinned to 9690622007)

Solutions

Read the docs appended to the error and fix the JSON object to match the schema.
Write `?` as content to `xd://<device>` to fetch the current schema before retrying.
Add missing required fields / correct field types per the underlying validation message.
If parameter names changed, migrate to the new names (check the device docs for renames).

Example fix

// before
write({ path: "xd://browser", content: "{\"goTo\":\"https://x.com\"}" })
// after
write({ path: "xd://browser", content: "{\"action\":\"navigate\",\"url\":\"https://x.com\"}" })

Defensive patterns

Strategy: try-catch

Validate before calling

// validate against the device schema before writing
const docs = await write({ path: `xd://${device}`, content: "?" });
// ensure args object keys match the documented required fields/types

Type guard

function argsMatchSchema(args: Record<string, unknown>, required: string[]): boolean { return required.every((k) => k in args); }

Try / catch

try { await write({ path, content: JSON.stringify(args) }); } catch (e) { if (String(e.message).startsWith("Invalid args for")) { console.error(e.message); /* message includes device docs; correct args and retry */ } else throw e; }

Prevention

Fetch device docs (`?` content) before the first call to a device.
Only send fields defined in the device schema; no guessed names.
Match exact types (string vs number) from the schema.
Retry with corrected args using the docs appended to the error.

When it happens

Trigger: Content is a valid JSON object but fails the device's schema validation — missing required fields, wrong types, unknown fields, or values violating constraints (e.g. non-enum action).

Common situations: An agent guesses parameter names instead of consulting the schema; hallucinated fields; wrong value type (string where number expected) after schema or device-version changes.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/3060b10f67fa9389. Report an issue: GitHub.