Troubleshooting

If something doesn’t behave as expected, you’re in the right place.

This section helps you identify symptoms quickly, understand why they happen, and apply the right fix without guesswork.

SotsAI is deterministic and stateless.
When something feels “off”, the cause is almost always integration logic, not hidden model behavior.

---

Quick diagnosis

Use the symptoms below to jump directly to the relevant guide.

---

SotsAI refuses to run or says profiles are required

Your system cannot generate advice because psychometric data is missing.

Most common causes:

• no user profile available
• orchestration layer did not fetch or inject profiles
• feature is called too early in the pipeline

→ No psychometric profile available

---

DISC profile cannot be fetched

Profile retrieval fails for a specific user.

Most common causes:

• the user was never invited
• the assessment was not completed
• email mismatch or wrong organization context

→ DISC profile not found

---

Requests fail due to quota or rate limits

Calls are rejected with quota or rate-limit errors.

Most common causes:

• monthly quota reached
• organization in read-only state
• burst traffic without backoff

→ Quota or rate limit exceeded

---

Advice generation fails unexpectedly

SotsAI returns an advice-generation error.

Most common causes:

• malformed or inconsistent input
• transient internal error
• timeout or retry exhaustion

→ Advice generation failed

---

The LLM never calls SotsAI

Profiles exist, tools are defined, but SotsAI is never invoked.

Most common causes:

• tool not exposed at the right time
• system prompt does not authorize usage
• tool schema too strict or misconfigured

→ LLM did not call SotsAI

---

How to use this section effectively

When debugging:

1. Start from the symptom, not the code
2. Follow the checks in the order listed
3. Validate assumptions (profiles present, tool called, output applied)
4. Add logging around:
   • tool exposure
   • tool invocation
   • SotsAI response metadata

If the issue persists after following the guide, you should already have:

• a clear failing step
• structured logs
• reproducible inputs

That’s usually enough to resolve the issue quickly.