langchain-ai/deepagents · error · ValueError

task() requires non-empty string field `description`

Error message

task() requires non-empty string field `description`

What it means

`_validate_task_payload` rejects JS `task()` calls whose payload has no `description` field, or whose `description` is not a non-empty string. The library requires a textual description because it is forwarded to the subagent as its instructions. The error is raised as a ValueError before any subagent is dispatched.

Source

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

        bridges = {camel: self._bridge_symbols[camel] for camel in target_names}
        ctx.eval(_render_tools_namespace_assignment(bridges))
        self._active_tool_names = target_names
        self._tools_installed = True

    @staticmethod
    def _validate_task_payload(
        payload: dict[str, Any],
    ) -> tuple[str, str, str | None, dict[str, Any] | None]:
        """Validate JS `task()` input and return its typed fields.

        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)

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Ensure the JS call includes a non-empty string `description`: `task({description: 'Find X', subagentType: 'researcher'})`
  2. If the payload is built dynamically, default/validate description before calling task()
  3. Check the system-prompt task() schema given to the model matches the expected keys

Example fix

// before
await task({ subagentType: 'researcher' })
// after
await task({ description: 'Summarize recent commits', subagentType: 'researcher' })
Defensive patterns

Strategy: validation

Validate before calling

function canCallTask(p) {
  return typeof p === 'object' && p !== null
    && typeof p.description === 'string' && p.description.length > 0;
}

Type guard

function isNonEmptyString(v) {
  return typeof v === 'string' && v.length > 0;
}

Try / catch

try {
  await task(payload);
} catch (e) {
  if (String(e).includes('description')) {
    throw new Error('task() payload missing non-empty description');
  }
  throw e;
}

Prevention

When it happens

Trigger: JS code in the QuickJS eval calls `task()` with a missing, null, non-string, or empty-string `description` field, e.g. `task({subagentType: 'researcher'})` or `task({description: '', ...})`.

Common situations: Model-generated JS omitting `description` because the prompt schema was mis-remembered, dynamic payload built with `undefined` fields, or camelCase/snake_case confusion passing `subagent_type` instead of `subagentType`.

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 langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/b78e940ccaa2e584. Report an issue: GitHub.