Skip to content

Confusing error message when running 'adk web' on agent directory instead of parent #3195

@jpantsjoha

Description

@jpantsjoha

Problem

When users run adk web pointing directly to an agent directory instead of the parent directory, they encounter a confusing error message:

RuntimeError: [WIP] _load_from_yaml_config: _load_from_yaml_config is not ready for use.

This error doesn't explain:

  • What the actual problem is
  • How to fix it
  • Where adk web should be pointed

Steps to Reproduce

# Assume this directory structure:
# my_project/
# ├── my_agent/
# │   └── agent.py

# Incorrect (triggers error):
adk web my_agent/

# Correct (works):
adk web .

Current Behavior

Users see:

RuntimeError: [WIP] _load_from_yaml_config: _load_from_yaml_config is not ready for use.

Expected Behavior

The error message should guide users:

RuntimeError: [WIP] _load_from_yaml_config: _load_from_yaml_config is not ready for use.

Tip: Ensure you're running 'adk web' on the parent directory containing 
your agent folder, not the agent folder itself.

Example:
  ✅ adk web .               (parent directory)
  ❌ adk web my_agent/       (agent directory)

Impact

This issue has affected multiple teams during solution development workshops, causing confusion and wasted debugging time.

Proposed Fix

Add helpful context to the error message in src/google/adk/cli/utils/agent_loader.py around line 178.


Labels: bug, good first issue, documentation
Priority: Low (UX improvement)

Metadata

Metadata

Assignees

Labels

web[Component] This issue will be transferred to adk-web

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions