srbhr/Resume-Matcher · error · HTTPException

Resume wizard failed. Please try again.

Error message

Resume wizard failed. Please try again.

What it means

A 500 raised by resume_wizard_turn for any unexpected exception from run_ai_turn that is not an HTTPException or ValueError — typically failures inside the AI turn pipeline itself. Signals an unhandled server-side problem; the cause is logged as 'Resume wizard turn failed'.

Source

Thrown at apps/backend/app/routers/resume_wizard.py:63

        # answer/skip turns and route the user to review instead of advancing.
        if request.state.asked_count >= RESUME_WIZARD_MAX_QUESTIONS:
            return ResumeWizardTurnResponse(state=apply_review(request.state))

        if action == "skip":
            state = await run_ai_turn(request.state, "", skip=True)
            return ResumeWizardTurnResponse(state=state)

        answer_text = request.answer.text if request.answer else ""
        state = await run_ai_turn(request.state, answer_text, skip=False)
        return ResumeWizardTurnResponse(state=state)
    except HTTPException:
        raise
    except ValueError as e:
        logger.error("Resume wizard turn validation failed: %s", e)
        raise HTTPException(status_code=422, detail="Could not update the resume draft.")
    except Exception as e:
        logger.error("Resume wizard turn failed: %s", e)
        raise HTTPException(
            status_code=500,
            detail="Resume wizard failed. Please try again.",
        )


@router.post("/finalize", response_model=ResumeWizardFinalizeResponse)
async def finalize_resume_wizard(
    request: ResumeWizardFinalizeRequest,
) -> ResumeWizardFinalizeResponse:
    """Create the master resume from a validated wizard draft."""
    try:
        current_master = await db.get_master_resume()
        if current_master and current_master.get("processing_status") == "ready":
            raise HTTPException(
                status_code=409,
                detail="A master resume already exists. Delete it before creating a new one.",
            )

View on GitHub (pinned to 116f9cc3b0)

Solutions

1. Check server logs for 'Resume wizard turn failed' to identify the root exception
2. Verify the AI provider credentials, quota, and connectivity (often an env/config issue)
3. Retry the request — transient provider outages resolve on retry with backoff
4. If parsing-related, pin/fix the AI response schema handling in run_ai_turn

Example fix

// before: no handling, user sees raw 500
await submitWizardTurn(state, answer);
// after
try {
  await submitWizardTurn(state, answer);
} catch (e) {
  if (e.response?.status === 500) {
    showToast('Wizard is temporarily unavailable; retrying...');
    await retryWithBackoff(() => submitWizardTurn(state, answer));
  } else throw e;
}

// Pre-flight: confirm AI provider is configured before starting the wizard
if (!process.env.LLM_API_KEY) throw new ConfigError('LLM_API_KEY missing — wizard turns will fail');

try {
  await api.post('/resume-wizard/turn', { state, answer });
} catch (e) {
  if (e.response?.status === 500) {
    await retryWithBackoff(() => api.post('/resume-wizard/turn', { state, answer }), { retries: 2, baseMs: 1000 });
  } else throw e;
}

When it happens

Trigger: AI provider call fails (network, timeout, quota, invalid API key); unexpected None/malformed structure returned by the AI and dereferenced; database error while loading/saving wizard state that isn't a ValueError.

Common situations: Missing or expired LLM API key in the environment; provider rate limits or outage; prompt/response schema change in the AI layer breaking parsing; DB connectivity loss mid-turn.

Related errors

• Failed to save changes. Please try again.
• Could not create master resume.
• Resume content changed or could not be uniquely matched. Ple
• No job descriptions provided
• Empty job description

AI-assisted analysis of srbhr/Resume-Matcher@116f9cc3b0 (2026-08-28). Data as JSON: /api/errors/d21d86357290900d. Report an issue: GitHub.