deepset-ai/haystack · error · ValueError

Variable '{var_name}' from {prompt_source} conflicts with in

Error message

Variable '{var_name}' from {prompt_source} conflicts with input names in the run method. Please rename the variable or remove it from the prompt to avoid conflicts.

What it means

read_skill_file supports three content kinds: UTF-8 text, images (by MIME type), and PDFs. When the target file is none of those — its bytes fail UTF-8 decoding and it isn't a recognized image or PDF — this ValueError is raised (chained from UnicodeDecodeError). It guards against handing binary garbage to the model as text.

Source

Thrown at haystack/components/agents/agent.py:583

            if builder is not None:
                # set required_variables on the builder, filtered to its own variables
                if required_variables == "*":
                    builder.required_variables = "*"
                elif isinstance(self.required_variables, list):
                    builder.required_variables = [v for v in self.required_variables if v in builder.variables]

                for var_name in builder.variables:
                    all_variables.setdefault(var_name, []).append(label)

        for var_name, sources in all_variables.items():
            prompt_source = " and ".join(sources)
            if var_name in self.resolved_state_schema:
                raise ValueError(
                    f"Variable '{var_name}' from {prompt_source} is already defined in the state schema. "
                    "Please rename the variable or remove it from the prompt to avoid conflicts."
                )
            if var_name in self._run_method_params:
                raise ValueError(
                    f"Variable '{var_name}' from {prompt_source} conflicts with input names in the run method. "
                    "Please rename the variable or remove it from the prompt to avoid conflicts."
                )
            if required_variables == "*" or (isinstance(required_variables, list) and var_name in required_variables):
                component.set_input_type(self, name=var_name, type=Any)
            else:
                component.set_input_type(self, name=var_name, type=Any, default=None)

    def warm_up(self) -> None:
        """Warm up the tools, hooks, and the underlying chat generator."""
        warm_up_tools(tools=self.tools)
        warm_up_hooks(self.hooks)
        if hasattr(self.chat_generator, "warm_up"):
            self.chat_generator.warm_up()

    async def warm_up_async(self) -> None:
        """Warm up the tools, hooks, and the underlying chat generator on the serving event loop."""
        warm_up_tools(tools=self.tools)

View on GitHub (pinned to e318778c9b)

Solutions

1. Read a supported file instead: convert the asset to UTF-8 text, PNG/JPEG image, or PDF and rebundle the skill.
2. If the file is text in another encoding, re-save it as UTF-8 (e.g. iconv -f latin-1 -t utf-8 file.txt).
3. Read the file yourself with plain I/O outside the skill store if you genuinely need raw binary bytes.

Example fix

// before
content = store.read_skill_file("my-skill", "data.xlsx")
// after
with open("skills/my-skill/data.xlsx", "rb") as f:
    raw = f.read()  # or convert the data to CSV and read that via the store

import mimetypes
from pathlib import Path

SUPPORTED = {"text/plain", "application/pdf", "image/png", "image/jpeg", "image/gif", "image/webp"}

def is_readable_asset(path: str) -> bool:
    mime, _ = mimetypes.guess_type(path)
    if mime and mime in SUPPORTED:
        return True
    try:
        Path(path).read_text(encoding="utf-8")
        return True
    except (UnicodeDecodeError, OSError):
        return False

try:
    content = store.read_skill_file(name, path)
except ValueError as e:
    if "not a readable asset" in str(e):
        logger.warning("Skipping unsupported binary asset %r", path)
        content = None
    else:
        raise

When it happens

Trigger: Reading binary assets like .zip, .xlsx, .docx, .exe, or unknown-extension binary blobs from a skill directory via read_skill_file; also corrupted text files with invalid byte sequences.

Common situations: Skills bundling datasets/archives that the store can't render; users expecting every bundled file to be readable; files saved in a non-UTF-8 encoding (e.g. latin-1) with exotic characters; truncated downloads.

Related errors

• Invalid hook point '{hook_point}'. Valid hook points are: {'
• Hook registered for hook point '{hook_point}' is callable bu
• Hook registered for hook point '{hook_point}' must have a ca
• Hook of type '{type(h).__name__}' is registered under hook p
• {type(chat_generator).__name__} does not accept tools parame

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/818025a587f72a2c. Report an issue: GitHub.