bytedance/deer-flow · error · SlashSkillCommandResolutionError

Failed to resolve slash skill command. Please check the skil

Error message

Failed to resolve slash skill command. Please check the skill configuration.

What it means

Slash-skill resolution (mapping '/skillname' in an IM message to an installed skill) wraps its whole lookup in a try/except; any unexpected exception — registry read failure, malformed skill metadata, a bug in the matcher — is logged with a traceback and re-raised as SlashSkillCommandResolutionError with this operator-facing message. It deliberately hides the raw cause from the IM user while preserving it via `from exc`.

Source

Thrown at backend/app/channels/manager.py:802

    reference = parse_slash_skill_reference(text)
    if reference is None:
        return None
    try:
        resolved_storage = storage() if callable(storage) else storage or get_or_new_skill_storage()
        skills = resolved_storage.load_skills(enabled_only=False)

        skill = next((candidate for candidate in skills if candidate.name == reference.name), None)
        if skill is None:
            return None
        if not skill.enabled:
            return _SlashSkillCommandResolution(failure_message=f"Skill `/{reference.name}` is installed but disabled. Enable it before using slash activation.")
        if available_skills is not None and reference.name not in available_skills:
            return _SlashSkillCommandResolution(failure_message=f"Skill `/{reference.name}` is not available for this agent.")

        return _SlashSkillCommandResolution(route_to_chat=True)
    except Exception as exc:
        logger.exception("[Manager] failed to resolve slash skill command")
        raise SlashSkillCommandResolutionError("Failed to resolve slash skill command. Please check the skill configuration.") from exc


def _resolve_attachments(thread_id: str, artifacts: list[str], *, user_id: str | None = None) -> list[ResolvedAttachment]:
    """Resolve virtual artifact paths to host filesystem paths with metadata.

    Only paths under ``/mnt/user-data/outputs/`` are accepted; any other
    virtual path is rejected with a warning to prevent exfiltrating uploads
    or workspace files via IM channels.

    Skips artifacts that cannot be resolved (missing files, invalid paths)
    and logs warnings for them.
    """
    from deerflow.config.paths import get_paths

    attachments: list[ResolvedAttachment] = []
    paths = get_paths()
    effective_user_id = user_id or get_effective_user_id()
    outputs_dir = paths.sandbox_outputs_dir(thread_id, user_id=effective_user_id).resolve()

View on GitHub (pinned to 1dd6ba1acb)

Solutions

Read the Gateway logs — the logger.exception line right above the user-facing error contains the underlying traceback and offending skill.
Validate skill packages with the built-in skill-reviewer or reinstall the offending skill (`make extension-*` / skills tooling).
Re-sync extensions_config.json with actually-present skills (remove entries whose directories are gone).
After fixing, restart the Gateway so the skill registry reloads cleanly.

Defensive patterns

Strategy: try-catch

Validate before calling

def skill_registry_healthy() -> bool:
    try:
        skills = list_installed_skills()
        return all(os.path.isdir(s.path) for s in skills)
    except Exception:
        return False

Try / catch

try:
    resolution = resolve_slash_skill(text)
except SlashSkillCommandResolutionError as e:
    logger.exception('slash resolution failed')
    reply('That skill could not be activated. Please contact the operator.')
    return

Prevention

Validate skill packages with skill-reviewer before installation.
Keep extensions_config.json and the skills directory in sync (remove entries for deleted skills).
Run a registry smoke check at Gateway startup so misconfiguration is caught before users message.

When it happens

Trigger: An IM user sends '/<skill>' and, during resolution, the skills registry throws: unreadable/corrupt skill metadata file, a skills directory entry with invalid YAML/JSON frontmatter, or a projection that has not been generated. The channel manager logs '[Manager] failed to resolve slash skill command' and surfaces this error to the chat.

Common situations: A manually installed skill with broken SKILL.md frontmatter; file permissions blocking the skills directory; concurrent writes to the skills config while a message arrives; a skill removed from disk but still listed in extensions_config.json.

Related errors

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/ba1d94c20a2239d2. Report an issue: GitHub.