iflytek/astron-agent · error · PluginExc

-1

-1

Error message

CHUNK_QUERY_URL is not set

What it means

KnowledgePlugin.retrieve() reads CHUNK_QUERY_URL to know where the knowledge/RAG chunk-query service lives. If the env var is absent it raises PluginExc(code=-1) before making any HTTP call — a fail-fast guard against an unconfigured retrieval endpoint.

Solutions

  1. Set CHUNK_QUERY_URL (e.g. http://knowledge:8080/chunk/query) in the Agent service environment and restart it
  2. Add the variable to docker-compose/helm values so every deployment includes it
  3. Locally, export CHUNK_QUERY_URL or put it in the .env file the service loads
  4. Add a startup readiness check that validates required env vars before serving traffic

Example fix

// before
export KNOWLEDGE_CALL_TIMEOUT=90
// after
export CHUNK_QUERY_URL=http://knowledge-service:8080/api/chunk/query
export KNOWLEDGE_CALL_TIMEOUT=90
Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.getenv("CHUNK_QUERY_URL"):
    raise RuntimeError("CHUNK_QUERY_URL must be set before invoking the knowledge plugin")

Type guard

def knowledge_configured() -> bool:
    url = os.getenv("CHUNK_QUERY_URL")
    return bool(url and url.startswith(("http://", "https://")))

Try / catch

try:
    result = await plugin.retrieve(span)
except PluginExc as e:
    if "CHUNK_QUERY_URL" in str(e):
        logger.error("knowledge service URL missing; set CHUNK_QUERY_URL and restart")
    raise

Prevention

When it happens

Trigger: Invoking the knowledge plugin with non-empty repo_ids when CHUNK_QUERY_URL is not present in the Agent service environment (knowledge.py:96-98).

Common situations: Agent container started without the knowledge service URL env var; .env file not loaded; value named differently in a new deployment template; the variable lost when copying compose files between environments.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/f8d9e69204d60871. Report an issue: GitHub.

Appendix: source

Thrown at core/agent/service/plugin/knowledge.py:98

            if self.rag_type == "Ragflow-RAG" and self.dataset_ids:
                data["match"]["datasetId"] = self.dataset_ids

            sp.add_info_events({"request-data": json.dumps(data, ensure_ascii=False)})

            if not self.repo_ids:
                empty_resp: Dict[str, Any] = {}
                sp.add_info_events(
                    {"response-data": json.dumps(empty_resp, ensure_ascii=False)}
                )
                retrieval_span.set_attributes(
                    self._retrieval_attributes(output_value=empty_resp)
                )
                return empty_resp

            try:
                query_url = os.getenv("CHUNK_QUERY_URL")
                if not query_url:
                    raise PluginExc(-1, "CHUNK_QUERY_URL is not set")
                async with aiohttp.ClientSession() as session:
                    timeout = aiohttp.ClientTimeout(
                        total=int(os.getenv("KNOWLEDGE_CALL_TIMEOUT", "90"))
                    )
                    headers = self._headers()
                    async with session.post(
                        query_url, headers=headers, json=data, timeout=timeout
                    ) as response:

                        sp.add_info_events(
                            {"response-data": str(await response.read())}
                        )

                        response.raise_for_status()
                        if response.status == 200:
                            resp: Dict[str, Any] = await response.json()
                            sp.add_info_events(
                                {"response-data": json.dumps(resp, ensure_ascii=False)}

View on GitHub (pinned to 5e758547a8)