Troubleshooting

#Troubleshooting

Common errors and solutions when using the mAIvn SDK. This is the cookbook: a specific error message, its cause, and a copy-pasteable fix. For the exception types behind these messages — the public MaivnSDKError hierarchy, validation failures, and how to structure a layered try/except — see Errors & Exceptions.

#Common Errors

#Agent requires either a Client instance or an api_key

Error:

ValueError: Agent requires either a Client instance or an api_key, or MAIVN_API_KEY in the process environment.

Cause: The agent could not resolve credentials from its arguments, selected credential file, or process environment.

Solution:

# Option 1: Provide api_key
agent = Agent(name='my_agent', api_key='your-api-key')

# Option 2: Use environment variable
# Set MAIVN_API_KEY in your environment
agent = Agent(name='my_agent')

# Option 3: Provide a Client
client = Client(api_key='your-api-key')
agent = Agent(name='my_agent', client=client)

#Targeted tool selection fails

targeted_tools must contain at least one registered tool name. Unknown names raise ValueError listing the available tools. The SDK includes the selected tools' declared tool dependencies automatically.

targeted_tools can be combined with structured_output=Model in v2: selection happens first, then the SDK adds or promotes the final model constructor. It can also be combined with force_final_tool=True; include the intended final tool in the selected set.

#Multiple tools marked with final_tool=True

An agent can register multiple final tools in v2. The local tool validator rejects duplicate tool names, not multiple final-tool flags. If an older example tells you to remove all but one final tool, that restriction does not apply to this SDK.

Swarm validation has a separate ownership rule: when multiple member agents own final tools, designate one member with use_as_final_output=True. See the Swarm reference.

#Argument not found in function signature

Dependency decorators do not consistently validate parameter names when they are applied. A mismatch can surface later during schema compilation or execution. Check that arg_name matches the function parameter or Pydantic field exactly.

Solution: Use the correct parameter name:

# Wrong: arg_name doesn't match
@depends_on_tool(other_tool, arg_name='data')
def my_tool(result: dict) -> dict: ...

# Correct: arg_name matches parameter
@depends_on_tool(other_tool, arg_name='result')
def my_tool(result: dict) -> dict: ...

#force_final_tool requires at least one tool with final_tool=True

Error:

ValueError: force_final_tool=True requires at least one tool with final_tool=True.
Agent 'my_agent' has 3 tool(s) but none are final.

Cause: You used force_final_tool=True but no tool is marked as final.

Solution: Mark one tool as final:

@agent.toolify(final_tool=True)  # Add final_tool=True
class FinalOutput(BaseModel):
    result: str

# Or register the final model imperatively.
agent.add_tool(FinalOutput, final_tool=True)

If you use constructor-based tools, raw functions and models are registered with default tool options. Use agent.add_tool(..., final_tool=True) when a Pydantic model must be the agent's final tool.

#Connection errors

Error:

httpx.ConnectError: [Errno 111] Connection refused

Cause: Cannot connect to the mAIvn server.

Solutions:

1. Check that the mAIvn server is running
2. Verify the server URL in configuration
3. Check network connectivity
4. Verify firewall rules

#Timeout errors

Error:

httpx.ReadTimeout: timed out

Cause: The HTTP read exceeded its configured timeout while waiting for data.

Solutions:

# Increase timeout
client = Client(
    api_key='...',
    http_timeout=120,
)

The compatibility fields tool_execution_timeout, dependency_wait_timeout, and total_execution_timeout do not impose execution deadlines in the current SDK. An HTTP timeout does not cancel a server invocation. See Reliability.

#MCP server startup failure

Error:

ValueError: stdio MCPServer requires command or auto_setup

Cause: MCP server configuration is incomplete.

Solution:

# Provide command
MCPServer(
    name='my_server',
    transport='stdio',
    command='my-mcp-server',  # Add this
)

# Or use auto_setup
MCPServer(
    name='my_server',
    transport='stdio',
    auto_setup=MCPAutoSetup(package='my-mcp-package'),
)

#Memory retrieval returns no hits

Symptoms:

• Follow-up turns do not recall prior details
• memory_retrieved appears with low/zero hit count

Checks:

1. Reuse the same thread_id across turns.
2. Confirm memory is enabled (memory_config.enabled=True, or omit it and rely on scope defaults).
3. Confirm retrieval is enabled via memory_config.level (glimpse, focus, or clarity).
4. Verify org/project policy does not downscope memory behavior.
5. If testing immediately after a seed turn, wait briefly and retry (indexing is async).

#memory_indexed not observed

Cause (common):

• Persistence not enabled at effective policy level, or write path was downscoped by config.

Checks:

1. Confirm memory is enabled, its level is not none, and persistence_mode is not persist_none.
2. Confirm memory_config.level is not downscoped by policy.
3. Confirm workspace policy permits requested persistence mode.
4. Inspect enrichment stream for memory_indexing/memory_indexed events.

#Context still too large in long threads

Checks:

1. Do not rely on summarization_enabled: this compatibility field is not forwarded by the SDK.
2. Keep prompts focused and avoid repeated full-history payloads when not needed.
3. Use event tracing (agent.events().invoke(...)) to verify summarize phases are emitted.

#Debugging

#Enable Event Tracing

See detailed execution information:

response = agent.events().invoke(messages)

#Configure Logging

Set up file logging:

from pathlib import Path
from maivn import configure_logging

log_file = Path('logs/maivn.log')
log_file.parent.mkdir(exist_ok=True)

logger = configure_logging(log_file)

#Check Log Level

Attach a standard Python logging handler for console output:

import logging
from maivn import get_logger

handler = logging.StreamHandler()
handler.setLevel(logging.DEBUG)
get_logger().addHandler(handler)

The SDK logger does not read MAIVN_LOG_LEVEL. See the logging reference for handler configuration and file output.

#Inspect Tool Registration

List registered tools:

for tool in agent.list_tools():
    print(f'{tool.name}: {tool.description}')
    print(f'  final_tool: {getattr(tool, "final_tool", False)}')
    print(f'  dependencies: {getattr(tool, "dependencies", [])}')

#Compile Tools Without Executing

Inspect the local tool metadata and model-visible schemas:

tools = agent.compile_tools()
print(f'Tools: {len(tools)}')
for tool in tools:
    print(tool.name, tool.input_schema)

#FAQ

#How do I reuse a thread for multi-turn conversation?

# First turn
response1 = agent.invoke(
    [HumanMessage(content='Hello')],
    thread_id='my-conversation',
)

# Second turn (same thread_id)
response2 = agent.invoke(
    [HumanMessage(content='Follow up')],
    thread_id='my-conversation',
)

#Why isn't my tool being called?

1. Check the description - Make it clear when the tool should be used
2. Check the system prompt - Guide the LLM to use your tools
3. Use event tracing - Run with agent.events().invoke(...) to inspect decisions
4. Check tool registration - Use agent.list_tools()

#How do I handle large tool catalogs?

max_results is accepted for compatibility but does not limit v2 tool selection. Register only the tools the agent needs, filter toolsets at registration, or use targeted_tools for a specific invocation. Selected tools' dependencies are also included. See the tools guide.

#How do I cancel a running invocation?

Use client.cancel(session_id) or await client.acancel(session_id) to request cancellation of an active server invocation. Use its session ID, not the thread ID. Closing an HTTP connection or receiving a timeout does not send this request.

#Why are my private data values appearing in logs?

Private-data injection is not a general-purpose log scrubber. The SDK's Python logger does not sanitize arbitrary application log messages. Check tool code, exception messages, and HTTP debug logging for raw values before sharing logs. If a documented redaction path exposes a value, report the affected path with a sanitized reproduction. See the private-data guide.

#Environment Checklist

Before debugging, verify:

• [ ] An API key is available to your app and passed to Agent or Client
• [ ] mAIvn server is running and accessible
• [ ] Network connectivity to server
• [ ] Correct Python version (3.10+)
• [ ] All dependencies installed (uv sync or pip install maivn)

#Getting Help

If you're still stuck:

1. Check the API Reference
2. Review the Guides
3. Run a known-good app in mAIvn Studio and compare event traces
4. Inspect a failing run from the Executions explorer in the developer portal

#See Also

• Errors & Exceptions - The exception types behind these messages, the three failure layers, and layered handling patterns
• Logging Reference - SDK logging
• Configuration Reference - Environment variables
• Best Practices - Recommended patterns