Error Hints

The conda_error_hints plugin hook allows plugins to contribute structured next-step hints while conda renders a conda.CondaError.

This hook is for user-facing remediation, not telemetry. Plugins should yield CondaErrorHint objects and should not print directly. Conda appends the yielded hints to the error's existing guidance so terminal and --json output stay consistent.

Example

from conda import plugins
from conda.exceptions import PackagesNotFoundInChannelsError


@plugins.hookimpl
def conda_error_hints(error):
    if isinstance(error, PackagesNotFoundInChannelsError):
        yield plugins.types.CondaErrorHint(
            text="Check whether the package exists on your expected channel.",
            hint_code="check_expected_channel",
        )

With that plugin installed, conda appends the hint to the normal terminal guidance output:

PackagesNotFoundInChannelsError: The following packages are not available
from current channels:
  - missing-package

Next steps:
  - (check_expected_channel) Check whether the package exists on your expected channel.

The same hint is included in --json output:

{
  "error": "...",
  "exception_name": "PackagesNotFoundInChannelsError",
  "guidance": {
    "hints": [
      {
        "hint_code": "check_expected_channel",
        "text": "Check whether the package exists on your expected channel."
      }
    ],
    "hint_codes": ["check_expected_channel"]
  }
}

Conda invokes each conda_error_hints implementation independently while rendering expected errors. If one plugin raises or yields an invalid hint, conda logs the plugin failure at DEBUG level and continues rendering the original error plus any other valid hints.

Hint order is deterministic: conda invokes implementations by plugin name, preserves the order yielded by each implementation, and appends plugin hints after core guidance hints. If two hints use the same hint_code, the first hint wins, so core guidance takes priority over plugin guidance. Hook wrappers are skipped for this hook so conda can isolate failures per implementation.

Error hints vs. exception observers

Use conda_error_hints when a plugin wants to add user-facing next steps to an expected conda.CondaError. Hints are part of conda's normal error guidance model: conda controls ordering, deduplicates by hint_code, renders them in the terminal Next steps section, and includes them in --json under guidance.hints and guidance.hint_codes.

Use Exception Observers when a plugin needs to observe failures for telemetry, logging, demand tracking, or other side effects. Observers are fire-and-forget callbacks modelled after sys.excepthook(): their return value is ignored, and they should not mutate exceptions or print user-facing messages.

API reference

class CondaErrorHint

Return type to use when defining a conda error hints plugin hook.

For details on how this is used, see conda_error_hints().

Parameters:

• text -- Human-readable description of the action to take.

• hint_code -- Stable machine-readable identifier. Use snake_case.

hint_code: str

Stable machine-readable identifier. Use snake_case.

text: str

Human-readable description of the action to take.

conda_error_hints(error: conda.CondaError) → collections.abc.Iterable[conda.plugins.types.CondaErrorHint]

Register user-facing hints for expected conda errors.

This hook is invoked while rendering a conda.CondaError. Plugins receive the current error and yield structured CondaErrorHint objects that conda appends to the error's existing guidance. Plugins should not print directly from this hook.

Conda invokes implementations in deterministic plugin-name order and preserves the hint order yielded by each plugin. Existing core guidance hints win when a plugin yields the same hint_code. Hook wrappers are skipped so conda can isolate failures per implementation.

Use this hook for user-facing next steps. Use conda_exception_observers() for telemetry, logging, demand tracking, or other side effects.

Example:

from conda import plugins
from conda.exceptions import PackagesNotFoundInChannelsError


@plugins.hookimpl
def conda_error_hints(error):
    if isinstance(error, PackagesNotFoundInChannelsError):
        yield plugins.types.CondaErrorHint(
            text="Check whether the package exists on your expected channel.",
            hint_code="check_expected_channel",
        )

Returns:

An iterable of CondaErrorHint entries.