Skip to main content

Troubleshooting

Configuration Errors​

"Field required: organization_id" Config is incomplete. Re-download from NINA provisioning.

"max_timeout_seconds must be >= default_timeout_seconds"

execution:
  default_timeout_seconds: 300
  max_timeout_seconds: 3600  # Must be >= default, or 0 for unlimited

Connectivity​

"Access Denied" on SQS or S3 Your credentials may have expired. Re-download config.yaml from NINA provisioning.

"Connection timeout" The agent needs outbound HTTPS (port 443) to AWS. Check firewalls and security groups.

Tool Issues​

"Tool 'X' not registered" The workflow sent a tool_name that doesn't match any registered tool. Ensure:

  • Decorator tools are imported before agent.start()
  • Class/factory tools are registered with agent.register_tool("name", tool)
  • The name matches exactly what the workflow sends

"Tool execution timed out" Increase timeouts in config:

execution:
  default_timeout_seconds: 1800   # 30 minutes
  max_timeout_seconds: 0          # Unlimited

"No input files" / empty input_paths The workflow didn't provide input files for this execution. Check that the previous node in the workflow produces output, or use parameters instead.

Agent Behavior​

Agent starts but nothing happens

  • Check that NINA has sent a workflow execution with an External Tool node
  • Verify the agent logs show Starting queue polling
  • Set logging.basicConfig(level=logging.DEBUG) in your agent script to see polling activity

Same message processed repeatedly The agent failed to acknowledge the message. Check for errors in the logs right after Processing execution.

Agent using too much memory Reduce concurrency:

execution:
  max_concurrent_executions: 2
polling:
  max_messages: 2

Encrypted Credentials​

"Encrypted payload received but no encryption_key configured" Your config.yaml is missing the encryption_key field. Re-download from NINA provisioning.

"Failed to decrypt proxy payload" The encryption key doesn't match what NINA used to encrypt. Re-download config.yaml.

Multiple Agents​

Do not run more than one agent with the same config. Both agents will compete for the same SQS messages. When one picks up a message, the other won't see it — meaning tasks are split unpredictably between them. Only one agent instance per config.

Quick Diagnostic​

# Verify config is valid
python -c "
from beam_agent import BeamConfig
config = BeamConfig.from_yaml('config.yaml')
config.validate_for_backend()
print('Config OK')
print(f'Org: {config.agent.organization_id}')
print(f'Encryption: {\"yes\" if config.agent.encryption_key else \"no\"}')
"

Next Steps​