HR Agent Troubleshooting

Diagnosis steps for the most common problems between Hrida AI Studio, hrida-mcpo, and HridaOne. Container names below match the bundled Docker Compose files — adjust them to your deployment.

---

Quick health check

Run these in order:

# 1. Is HridaOne up?
docker exec hrida-ai-studio curl -s http://hridaone:8081/api/public/health

# 2. Can mcpo reach HridaOne?
docker exec hrida-mcpo curl -s http://hridaone:8081/api/public/health

# 3. Are the HR tools registered in mcpo?
curl -H "Authorization: Bearer <mcpo-api-key>" http://localhost:8000/hr-agent/openapi.json | head -c 300

# 4. Does a per-user token exist? (send the HR Agent a message or start a run first)
docker exec redis-valkey valkey-cli keys "hrida:kc_token:*"

# 5. SSO only — can HridaOne reach Keycloak?
docker exec hridaone curl -s http://keycloak:9090/realms/hrida/.well-known/openid-configuration | head -c 200

---

HR tool returns 401 Unauthorized

Cause A — Wrong or missing service account credentials

Check that HRIDAONE_EMAIL and HRIDAONE_PASSWORD (or HRIDAONE_JWT_TOKEN) are set in the hr-agent env block of mcpo's config.json. Verify the login directly:

curl -X POST http://hridaone:8081/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"hr-agent@yourcompany.com","password":"<password>"}'

A 200 with a token means the credentials work. A 401 means they are wrong, or the tenant only allows Keycloak sign-in — then use per-user tokens or a pre-issued HRIDAONE_JWT_TOKEN. See HridaOne Service Account.

Cause B — Keycloak token expired (SSO)

Keycloak access tokens last 5 minutes by default. If a long workflow outlives the token, HridaOne rejects later calls. Raise Realm Settings → Tokens → Access Token Lifespan (for example to 15 minutes).

Cause C — Token rejected by HridaOne (SSO)

The token's iss must match KEYCLOAK_ISSUER_URI or KEYCLOAK_PUBLIC_ISSUER_URI exactly (including any trailing slash), and its azp must be listed in KEYCLOAK_ALLOWED_CLIENT_IDS.

docker logs hridaone 2>&1 | grep -i "issuer\|azp\|signature\|jwks"

---

HR tool returns 403 Forbidden

The caller's HridaOne role doesn't allow the action. For example, get_admin_attendance_stats needs an HR manager or admin role. Promote the user in HridaOne, or check that JIT provisioning ran (below).

---

JIT provisioning not working (SSO)

Symptom: The user signs in to Studio through Keycloak, but HR tool calls fail with "user not found".

docker logs hridaone 2>&1 | grep -i "jit\|provision"

Missing hrida_tenant_code claim. JIT provisioning needs the tenant from the token. Decode the token's payload and check for the claim; if it's absent, add the mapper described in SSO Integration → Map the tenant code into the token.

Keycloak unreachable from HridaOne. If the logs show JWKS fetch errors, verify:

docker exec hridaone curl -s http://keycloak:9090/realms/hrida/protocol/openid-connect/certs

---

HR tools missing in chat or Agent Builder

1. Verify mcpo is running: docker ps | grep mcpo, then docker logs hrida-mcpo.
2. Check the tool server URL and API key under Admin Panel → Settings → Integrations → Manage Tool Servers.
3. Confirm the hr-agent entry exists in mcpo's config.json and the subprocess started:

   docker logs hrida-mcpo 2>&1 | grep -i "hr-agent\|error\|failed"

4. Verify HRIDAONE_API_URL is reachable from the mcpo container.

---

Per-user token not used (SSO)

Symptom: HR tool calls run as the service account, or fail with "please log in via Keycloak".

1. Per-user mode on? docker exec hrida-mcpo env | grep HRIDAONE_USE_PER_USER_TOKEN — must be true (or set in the hr-agent env block).
2. Token in Redis? Send a message or start a run, then check keys "hrida:kc_token:*". If nothing appears, check the worker logs: docker logs hrida-ai-studio-worker 2>&1 | grep -i "kc token".
3. Same Redis? Studio, the worker, and mcpo must share one REDIS_URL.
4. User session? Runs started by cron or webhook triggers, and users who signed in with email/password, have no Keycloak token — the service account is used.

---

Workflow run stuck in "running"

Cancel it:

curl -X POST http://localhost:3000/api/v1/agent-workflows/runs/<run_id>/cancel \
  -H "Authorization: Bearer <admin-token>"

The run's hrida:kc_token:{run_id} key expires on its own TTL.

---

Employee sees someone else's data

Likely cause: per-user tokens are off and the service account (admin-level) answered a request without the user's own employee ID.

1. Enable SSO and set HRIDAONE_USE_PER_USER_TOKEN=true for HridaOne-enforced isolation.
2. Without SSO, keep the HR Agent's filter in place — it injects the user's email so the agent looks up the right employee. See How users see their own data.

---

Getting more logs

docker logs hrida-ai-studio 2>&1 | grep -E "kc_token|workflow|run_id"   # Studio
docker logs hrida-ai-studio-worker 2>&1                                 # workflow worker
docker logs hrida-mcpo 2>&1                                             # tool calls
docker logs hridaone 2>&1                                               # auth filter, JIT, HR API