langchain-ai/deepagents · error · ValueError

task() field `label` must be a string when provided

Error message

task() field `label` must be a string when provided

What it means

`_validate_task_payload` rejects a `label` field that is present but not a string. Unlike `description`/`subagentType`, `label` is optional (null is allowed), but if provided it must be a string; it is trimmed and an empty string is normalized to None. Raised as a ValueError before dispatch.

Source

Thrown at libs/partners/quickjs/langchain_quickjs/_repl.py:558

        JS callers pass camelCase keys (`subagentType`, `responseSchema`) as
        documented in the system prompt; the returned tuple is snake_case for
        the Python dispatch path.
        """
        description = payload.get("description")
        if not isinstance(description, str) or not description:
            msg = "task() requires non-empty string field `description`"
            raise ValueError(msg)

        subagent_type = payload.get("subagentType")
        if not isinstance(subagent_type, str) or not subagent_type:
            msg = "task() requires non-empty string field `subagentType`"
            raise ValueError(msg)

        raw_label = payload.get("label")
        if raw_label is not None and not isinstance(raw_label, str):
            msg = "task() field `label` must be a string when provided"
            raise ValueError(msg)
        label = raw_label.strip() if isinstance(raw_label, str) else None
        if label == "":
            label = None

        response_schema = payload.get("responseSchema")
        if response_schema is not None and not isinstance(response_schema, dict):
            msg = "task() field `responseSchema` must be an object when provided"
            raise ValueError(msg)

        return description, subagent_type, label, response_schema

    async def _ainvoke_task_on_outer_loop(
        self,
        payload: dict[str, Any],
        *,
        state: _PTCState,
    ) -> Any:
        """Validate JS `task()` input and invoke the runner on the right loop.

View on GitHub (pinned to a1af029e6e)

Solutions

1. Remove the `label` field if it is not needed (it is optional)
2. Pass a non-empty string, e.g. `label: 'docs-search-1'`
3. Coerce to string in JS before calling: `label: String(myLabel)`

Example fix

// before
await task({ description: 'X', subagentType: 'researcher', label: 7 })
// after
await task({ description: 'X', subagentType: 'researcher', label: 'run-7' })

if (payload.label !== undefined && typeof payload.label !== 'string') {
  throw new Error('label must be a string');
}

function isValidLabel(v) {
  return v === undefined || v === null || typeof v === 'string';
}

try {
  await task(payload);
} catch (e) {
  if (String(e).includes('label')) {
    delete payload.label; // label is optional; drop invalid value
    return await task(payload);
  }
  throw e;
}

When it happens

Trigger: JS calls `task({..., label: 42})` or passes a non-string value (number, boolean, object, array) for the optional `label` field.

Common situations: Model-generated JS putting an id/number in `label`, a marshaled non-string from a JS expression, or confusion between `label` semantics and the required fields.

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

• task() requires non-empty string field `description`
• task() requires non-empty string field `subagentType`
• task() field `responseSchema` must be an object when provide
• task() requires an active ToolRuntime
• task tool not configured for this eval

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/4fa734701576c1dc. Report an issue: GitHub.