🔧 Troubleshooting

Common issues and direct fixes for the current Python SDK.

1. ImportError: No module named 'wyseos.mate'

Cause:

• SDK not installed in current environment
• Wrong Python interpreter

Fix:

pip install wyseos-sdk
python -c "from wyseos.mate import Client; print('ok')"

If you use a virtual environment, activate it first.

2. ConfigError: Configuration file not found: .../mate.yaml

Cause:

• load_config() cannot find the file path.

Fix:

from wyseos.mate import Client, ClientOptions
from wyseos.mate.config import load_config

try:
    client = Client(load_config("mate.yaml"))
except Exception:
    client = Client(ClientOptions(api_key="YOUR_API_KEY"))

3. ConfigError: Invalid YAML in configuration file

Cause:

• Invalid YAML format.

Fix:

• Use spaces for indentation.
• Ensure key/value pairs are valid.
• Keep config in this structure:

mate:
  api_key: "your-api-key"
  # jwt_token: "your-jwt-token"
  base_url: "https://api.wyseos.com"
  timeout: 30

4. ValidationError on config values

Common cases:

• API key empty: API key cannot be empty
• Invalid base URL: Base URL must start with http:// or https://
• Invalid timeout: must be in range 1-300

Fix:

from wyseos.mate import ClientOptions

opts = ClientOptions(
    api_key="YOUR_API_KEY",
    base_url="https://api.wyseos.com",
    timeout=30,
)

5. HTTP 401/403 Authentication failures

Cause:

• Invalid api_key / jwt_token
• Wrong environment base_url

Fix:

• Re-generate credentials from dashboard.
• Confirm one auth mode is configured.
• Confirm request mapping:
  • API key -> x-api-key
  • JWT -> Authorization (no Bearer prefix)

6. TaskRunner timeout or no completion

Cause:

• Task takes longer than completion_timeout
• WebSocket/network issues

Fix:

from wyseos.mate.task_runner import TaskExecutionOptions

options = TaskExecutionOptions(
    verbose=True,
    completion_timeout=900,
)

result = task_runner.run_task(
    task="Complex analysis task",
    options=options,
)
print(result.success, result.error)

7. run_interactive_session() appears idle

Cause:

• Interactive mode waits for server-side input requests.

Fix:

• Keep verbose=True to see stream/progress.
• Use stop / pause / exit during interactive loop when needed.

8. create_and_wait() timeout in Product API

Cause:

• Product analysis not completed within poll window.

Fix:

report = client.product.create_and_wait(
    product="Notion",
    poll_interval=20,
    max_attempts=60,
    on_poll=lambda attempt, status: print(f"[{attempt}] {status}"),
)

9. File upload fails

Cause:

• Unsupported extension
• File too large (> 10MB)

Supported extensions:

• .txt, .pdf, .png, .jpg, .jpeg, .md, .csv, .html, .htm, .rss, .xml, .gif, .py, .json

10. Version mismatch check

Use package metadata instead of runtime __version__ only:

pip show wyseos-sdk

Need More Help?

• GitHub Issues: mate-sdk-python/issues
• Support: [email protected]