home-assistant/core · error · IntentRecognitionError

intent-failed

intent-failed

Error message

Unexpected error during intent recognition

What it means

IntentRecognitionError with code intent-failed wraps any unexpected exception raised while the conversation agent processes the utterance (async_converse or the surrounding handling in recognize_intent). The original traceback is logged with 'Unexpected error during intent recognition' before rethrowing, so the log carries the true cause.

Source

Thrown at homeassistant/components/assist_pipeline/pipeline.py:1329

                    if tts_input_stream and self._streamed_response_text:
                        tts_input_stream.put_nowait(None)

                if agent_id == conversation.HOME_ASSISTANT_AGENT:
                    # Check if all targeted entities were in the same area as
                    # the satellite device.
                    # If so, the satellite should respond with an acknowledge beep
                    # instead of a full response.
                    all_targets_in_satellite_area = (
                        self._get_all_targets_in_satellite_area(
                            conversation_result.response,
                            self._satellite_id,
                            self._device_id,
                        )
                    )

        except Exception as src_error:
            _LOGGER.exception("Unexpected error during intent recognition")
            raise IntentRecognitionError(
                code="intent-failed",
                message="Unexpected error during intent recognition",
            ) from src_error

        _LOGGER.debug("conversation result %s", conversation_result)

        self.process_event(
            PipelineEvent(
                PipelineEventType.INTENT_END,
                {
                    "processed_locally": processed_locally,
                    "intent_output": conversation_result.as_dict(),
                },
            )
        )

        if conversation_result.continue_conversation:
            self._conversation_data.continue_conversation_agent = agent_id

View on GitHub (pinned to 58a3fdb3ea)

Solutions

  1. Read the chained traceback in the Home Assistant log — it identifies the failing integration and line.
  2. If it is an LLM backend failure, verify the backend is reachable and the API key/model config is valid, then retry.
  3. Update or fix the custom agent/integration that the traceback points to.
  4. As a workaround, switch the pipeline to the default Home Assistant conversation agent to isolate the fault.
Defensive patterns

Strategy: try-catch

Try / catch

from homeassistant.components.assist_pipeline.error import IntentRecognitionError
try:
    await pipeline_job.run()
except IntentRecognitionError as err:
    if err.code == "intent-failed":
        _LOGGER.error("Intent failed: %s", err.__cause__)  # true cause is chained

Prevention

When it happens

Trigger: The selected conversation agent raises during processing: an LLM integration's API call fails unexpectedly, the default intent handler hits a bug in an intent/entity action, or response post-processing (_get_all_targets_in_satellite_area and similar) throws.

Common situations: OpenAI/Google/Ollama agent hitting a malformed API response or unhandled client error, Ollama server down with an error type not translated to HomeAssistantError, custom conversation agents raising arbitrary exceptions, or bugs in entity actions invoked by intents.

Related errors

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/5bdc2a20ac9a4074. Report an issue: GitHub.