zylon-ai/private-gpt · error · ValueError

Invalid system specification: {system}

Error message

Invalid system specification: {system}

What it means

Raised by the async deletion endpoint when the configured scheduler raises NotImplementedError from delete_async(). Same class of failure as async ingestion: the active IngestionScheduler has no async backend, so asynchronous document deletion cannot be dispatched and the API returns 501.

Source

Thrown at private_gpt/chat/input_models.py:254

                    known_citations=list(
                        {
                            *(potential_system.citations.known_citations or []),
                            *(item.citations.known_citations or []),
                        }
                    ),
                ),
                extensions=list(
                    dict.fromkeys(
                        [*(potential_system.extensions or []), *(item.extensions or [])]
                    )
                ),
                blob_visibility=item.blob_visibility,
            )

        return potential_system

    # Unknown type
    raise ValueError(f"Invalid system specification: {system}")


SystemOrStr = Annotated[System, BeforeValidator(validate_system_config)]


class ToolChoice(BaseModel):
    """Configuration for tool selection behavior during AI interactions."""

    type: Literal["auto", "any", "tool", "none"] = Field(
        default="auto", description="Tool selection strategy"
    )
    name: str | None = Field(
        default=None, description="Name of the tool to use if not auto-selecting"
    )
    disable_parallel_tool_use: bool = Field(
        default=False,
        description="When true, prevents the AI from using multiple tools simultaneously",
    )

View on GitHub (pinned to 4a030776a3)

Solutions

1. Use the synchronous deletion endpoint when running without an async scheduler.
2. Configure the Celery scheduler (broker, backend, running workers) to enable async deletion.
3. Check settings for the scheduler mode after upgrades.

Example fix

# before
POST /ingest/delete/async   # 501

# after
POST /ingest/delete   # synchronous path
# or configure celery scheduler and retry async

const asyncDeletionSupported = await probeAsyncCapability(); // false on 501 probe
if (!asyncDeletionSupported) useSyncDelete = true;

try { return await api.deleteAsync(body); }
catch (e) {
  if (e.status === 501) return api.deleteSync(body);
  throw e;
}

When it happens

Trigger: POST to /ingest/delete/async while running a scheduler without async support (no Celery); workers/broker not configured despite async routes being mounted.

Common situations: Same as async ingest: local dev profile without Celery; deployment where the async scheduler flag was lost during config migration; SDK auto-selecting async API from the OpenAPI spec.

Related errors

• Invalid system item in list: {item}
• Invalid system item in list (dict): {item}
• Invalid message order: expected {expected_roles} after {prev
• Schema must be a dictionary representing JSON Schema
• Handler must define function handle(input, context).

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/0f4c4045bfb36b08. Report an issue: GitHub.