wandb.errors.UsageError
wandb.errors.UsageError
Stack trace
wandb.errors.UsageError: Sweep agent failed to start: missing or invalid sweep configuration parameter 'method'
File "wandb/sdk/wandb_sweep.py", line 123, in start_agent
raise UsageError("Sweep configuration missing required fields")
File "wandb/sdk/wandb_sweep.py", line 98, in _validate_sweep_config
assert 'method' in config, "Sweep config must specify 'method'"
AssertionError: Sweep config must specify 'method' Why it happens
WandB sweep agents require a properly formatted sweep configuration YAML or dictionary including mandatory fields like 'method', 'parameters', and 'metric'. Missing or malformed fields cause the agent to raise a UsageError and fail to start. This often happens when the sweep config file is incomplete or incorrectly loaded.
Detection
Validate your sweep configuration file before launching the agent by checking for required keys like 'method' and 'parameters'. Use wandb.sweep.validate_config() or catch wandb.errors.UsageError exceptions to log detailed config errors.
Causes & fixes
Sweep configuration YAML missing the required 'method' field
Add a valid 'method' field to your sweep config, e.g., method: grid, random, or bayes.
Sweep config file path is incorrect or file is empty
Ensure the sweep config file path is correct and the file contains valid YAML with all required fields.
Parameters section in sweep config is malformed or missing
Define a proper 'parameters' section with parameter names and distributions or values as per WandB sweep schema.
Agent launched without specifying the sweep ID or with a wrong ID
Use the correct sweep ID returned by wandb.sweep() when starting the agent, e.g., wandb.agent(sweep_id).
Code: broken vs fixed
import wandb
sweep_config = {
# 'method' key missing here
'parameters': {
'learning_rate': {'values': [0.01, 0.001, 0.0001]}
}
}
sweep_id = wandb.sweep(sweep_config)
wandb.agent(sweep_id) # This line triggers wandb.errors.UsageErrorimport os
import wandb
# Set your WANDB_API_KEY in environment variables
os.environ['WANDB_API_KEY'] = os.getenv('WANDB_API_KEY')
sweep_config = {
'method': 'grid', # Added required 'method' field
'parameters': {
'learning_rate': {'values': [0.01, 0.001, 0.0001]}
}
}
sweep_id = wandb.sweep(sweep_config)
wandb.agent(sweep_id) # Fixed: sweep config now valid
print('Sweep agent started successfully')Workaround
Wrap wandb.sweep() and wandb.agent() calls in try/except wandb.errors.UsageError, log the error message, and manually verify or fix the sweep config file before retrying.
Prevention
Always validate your sweep configuration YAML or dict against WandB's schema before launching agents, and automate config checks in CI pipelines to catch missing fields early.