zylon-ai/private-gpt · error · ValueError

Only one SkillArtifact is supported per skill management too

Error message

Only one SkillArtifact is supported per skill management tool.

What it means

Raised by the SkillManagementProcessor when a skill management tool's context contains more than one SkillArtifact. SkillManagementToolBuilder takes a single skill_filter, so multiple skill scopes on one tool are ambiguous.

Source

Thrown at private_gpt/components/tools/processors/skill_management_processor.py:112

                        builder.build_list_skills(
                            name=tool.name or SKILL_LIST_TOOL_NAME,
                            type=tool.type or SKILL_LIST_TOOL_NAME + "_v1",
                        )
                    ],
                )
        return built_any

    def _make_builder(
        self, request: ResolvedChatRequest, tool: Any
    ) -> SkillManagementToolBuilder:
        tool_context = _get_tool_context(request, tool)
        skill_artifacts = [a for a in tool_context if isinstance(a, SkillArtifact)]
        if not skill_artifacts:
            raise ValueError(
                "Skill management tools require a SkillArtifact in the tool context."
            )
        if len(skill_artifacts) > 1:
            raise ValueError(
                "Only one SkillArtifact is supported per skill management tool."
            )
        return SkillManagementToolBuilder(
            skill_service=self._skill_service,
            skill_filter=skill_artifacts[0].skill_filter,
            skill_injection_mode=self._settings.skills.skill_injection_mode,
        )

View on GitHub (pinned to 4a030776a3)

Solutions

Keep exactly one SkillArtifact per skill management tool
Issue separate requests (or separate tool entries) for additional skill scopes
Merge the desired skill sets into one SkillArtifact with a combined skill_filter if the filter type allows

Example fix

# before
context=[SkillArtifact(filter_a), SkillArtifact(filter_b)]
# after
context=[SkillArtifact(filter_a)]  # separate request for filter_b

Defensive patterns

Strategy: validation

Validate before calling

skills = [a for a in (tool_context or []) if isinstance(a, SkillArtifact)]
assert len(skills) == 1, "skill management tools accept exactly one SkillArtifact"

Try / catch

try:
    resp = await client.chat(request)
except ValueError as e:
    if "Only one SkillArtifact" in str(e):
        # keep first SkillArtifact, issue extra requests for the others
        raise

Prevention

Make skill scope single-select in clients
Warn or dedupe when merging request templates that each carry a SkillArtifact
Document one-artifact-per-tool as an invariant next to tool context APIs

When it happens

Trigger: Attaching two or more SkillArtifact entries to the same skill management tool in one request.

Common situations: Users multi-selecting skill sets in a UI; composing a request that unions several skill scopes; accidentally duplicating the artifact during request assembly.

Related errors

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