> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hazel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting and FAQ

> Match what you are seeing to the symptom, and get the answers advisors and firm owners ask most.

You need to know whether what you are seeing is a problem before this plan goes in front of a client.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The build stopped and says Waiting for answer">
    Nothing is broken. Step two of three, badged **STEP 2 / 3**, is where Hazel asks the handful of things that would change the plan, one at a time and numbered. Answer them and the build carries on.

    Rather not decide? **Make reasonable assumption** settles the one in front of you, and a second option covers the rest. On the household's **Financial Planning** tab an untouched question takes that assumption itself after about half a minute; hovering or typing pauses the timer. In a chat it waits as long as you need.
  </Accordion>

  <Accordion title="Build didn't finish">
    The household's **Financial Planning** tab says this when a build stops short. Nothing you uploaded is lost: **Try again** picks up from the documents Hazel already read and the answers you gave. **Start over** clears the attempt and returns you to the readiness view, for when the data was the real problem. If a build fails twice, contact support and name the household.
  </Accordion>

  <Accordion title="The build is taking a while, or I navigated away">
    The card that starts a build estimates 5-15 min, and the reading step says 5-12 minutes; a household with a lot of paperwork runs longer. Hazel keeps working whether or not you watch, and chimes when the draft is ready; the speaker button beside the progress badge mutes the chime.

    On the household's **Financial Planning** tab the badge estimates the time left, counts the pages read, and past its usual time reads **Taking longer than usual**. Do not start a second build; wait for the plan, then ask for changes.
  </Accordion>

  <Accordion title="The plan says it couldn't find a figure I know we have">
    Hazel states what it cannot evidence instead of guessing, so check in order:

    1. **Could Hazel read the file?** During a build, the file list on the household's **Financial Planning** tab marks each document waiting, reading or read, and flags any Hazel could not read. Ask the client for a clean copy, or attach another in the plan's chat.
    2. **Can the plan see it?** A document has to be attached to the plan's own chat or held on the household; **Prepare data** on that tab does both, uploading to the household's **Documents** tab.
    3. **Is the fact unconfirmed?** Hazel uses unconfirmed facts and labels them Unverified in a figure's sources. On the household's **Data** tab, choose **Review** and use **Verify**. See [Reviewing and verifying](/guides/intelligent-client-profiles/managing-client-data/reviewing-and-verifying).
    4. **Waiting on an account sync?** A sync never delivers planning figures: those come from documents, meetings, emails and notes, so upload the statement.

    Then use **Regenerate**, in the top bar of the household's **Financial Planning** tab. See [Documents and CRM data](/guides/financial-planning/your-data/documents-and-crm).
  </Accordion>

  <Accordion title="A figure looks wrong">
    A figure with something recorded behind it carries a faint dotted underline. Select it to open a detail panel:

    * **Sources.** Which document, meeting, email or note it came from, each row carrying the value that source gave and a confidence chip: **Verified** where a document or a correction of your own settled it, **Unverified** where nobody has confirmed what was said, **Modeled** where nobody stated the figure and the plan worked it out. No dates here, so open the document itself if you suspect an old statement.
    * **Methodology.** The calculation, step by step, each input tied to its source.
    * **Assumptions.** Where one is yours to change you get **Edit**, then **Queue change**; the figure updates when you press **Recalculate** in the bar at the bottom of the plan.

    A figure with nothing recorded renders as plain text and will not open. Try the plan's **Appendix**, the last entry in its left navigation, which gathers all three for the whole plan, or ask in the plan's chat, which produces no new version. See [Where numbers come from](/guides/financial-planning/your-data/where-numbers-come-from).
  </Accordion>

  <Accordion title="I can't save my edits and the bar only offers Discard">
    A new version landed while your edits were staged, so **Discard my changes** is the only button in the bar at the bottom of the plan. Discarding keeps no copy, so copy anything you want out of the plan first, then read the new version and redo the edit. See [Editing a plan directly](/guides/financial-planning/the-plan/editing-a-plan-directly).
  </Accordion>

  <Accordion title="The export won't produce a PDF">
    A grayed-out **Export PDF** means changes are staged: save or discard them in the bar at the bottom of the plan. Moving a lever stages nothing, so where you only moved dials, look for a goal card you dragged into a new order, which does. The PDF renders the last saved version. If you got a message instead:

    | Message                               | What to do                                                                                                                                                                     |
    | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | PDF generation is busy                | Wait the few seconds it names, then try again                                                                                                                                  |
    | PDF export is temporarily unavailable | Try again in a few minutes                                                                                                                                                     |
    | The PDF download was invalid          | Nothing reached your machine, so run the export again                                                                                                                          |
    | This plan isn't ready to export       | Open the plan in its chat, use **Ask Hazel to repair plan**, wait for the new version, then export. From the household's **Financial Planning** tab, press **Open chat** first |
    | Couldn't export PDF                   | Try again, and if it happens twice use the thumbs-down in the plan's own conversation                                                                                          |
  </Accordion>

  <Accordion title="Hazel declined my request">
    The reply names the reason.

    * **A guardrail forbids it.** Nothing overrides your firm's absolute rules, Hazel included, and only a firm owner can change one, in **Settings → Planning**. See [Guardrails](/guides/financial-planning/assumptions/guardrails).
    * **A number your firm set says otherwise.** These bend: say why you want the change and ask again. For this plan, use **Plan settings** in the plan's own conversation; for every plan, a firm owner changes it in Planning settings.
    * **Nothing in the household's data supports the figure.** Add the document that carries it, or let the plan name the labeled assumption it used instead.
  </Accordion>

  <Accordion title="A section our template requires is missing from the plan">
    Ask in the plan's chat, naming the section: "Why is there no estate section in this plan?" Hazel answers from the plan itself, with no new version.

    Under **Guided** strictness Hazel may leave a block out when the household's facts do not support it. Under **Flexible**, where an unconfigured firm starts, Hazel composes each plan freely from your design. The durable fix belongs to a firm owner, in **Settings → Planning**:

    * In the **Plan design** card, use **Design layout** and select the block. **When it shows up** decides between **Always** and **When it applies**, and a **Leave out when** condition may be broader than you meant.
    * For a section that has to appear every time, set strictness to **Exact**. Hazel then holds each finished plan against your design and sends one that misses a block back to be fixed, though now and then a plan still publishes with something not matching, so read the next one or two. A household whose facts do not support a section still gets one, so it can read thin.

    See [Strictness](/guides/financial-planning/settings/personas/strictness).
  </Accordion>

  <Accordion title="The plan used the wrong Client persona">
    Open the plan's **Appendix**: the first row of **Applied settings** names the persona this version was built from, or reads None.

    For this plan, open its chat and name the one you want: "Rebuild this against our Pre-Retiree persona." A rebuild writes fresh content, so hand-edited wording does not come along.

    For every plan after this one, rewrite the persona's **description**, the strongest matching signal; the age band is only a hint, so a vague description keeps matching households you did not mean. See [Client personas](/guides/financial-planning/settings/personas/overview).
  </Accordion>

  <Accordion title="I changed a setting and the plan didn't change">
    Planning settings apply to the next plan, or to the next change to an existing one; a published plan stays as it was built, and its **Appendix** records the settings behind it.

    Bring a household onto the new settings with **Regenerate** in the top bar of the household's **Financial Planning** tab. Grayed out and reading that a plan update is in progress means Hazel is still working in that plan's chat, so give it a minute. After a persona change, check the **Appendix** for the persona this household matched.
  </Accordion>

  <Accordion title="Our persona stopped picking up base template changes">
    If it is one of the three Hazel installs, nobody edited anything: HENRY, Pre-Retiree and Retiree / Decumulator each arrive carrying their own plan design, so all three read **Customized** from the first time you open Planning settings, and base-template changes have never reached them.

    A persona your firm created follows the base template live until someone edits that persona's own design, then keeps its copy; the **Plan design** card says which state it is in.

    **Re-sync from base** moves a persona onto the base layout and discards the design it has now, so copy anything you want to keep first. Hazel asks you to confirm. See [Inheritance and re-syncing](/guides/financial-planning/settings/personas/inheritance).
  </Accordion>

  <Accordion title="I moved a lever but the words around it still say the old thing">
    A lever recalculates the figures wired to it, in your browser, and leaves the narrative alone. Moving one saves nothing.

    If the numbers move far enough that the prose is now wrong, ask Hazel to update that section and it comes back as a new version. See [Levers and scenarios](/guides/financial-planning/the-plan/levers-and-scenarios).
  </Accordion>

  <Accordion title="A colleague can't see a plan I built">
    Today a plan belongs to the advisor who built it, so a colleague with full access to the household can open its **Financial Planning** tab and still see no plan. Export the PDF and send it, or have them build their own; sharing financial-plan chats is a fast follow. Check household access too, without which they cannot open the household at all. See [Roles and permissions](/guides/settings/members/roles-and-permissions).
  </Accordion>

  <Accordion title="Still stuck">
    The thumbs live on the plan in its own conversation; from the household's **Financial Planning** tab, use **Open chat** in the plan's top bar. Press the thumbs down, labeled Not helpful plan, and a short form opens: pick the kind of issue (UI bug, Not factually correct, Incomplete response, Didn't follow request, or Other) and say what you expected. Your note travels with the version you were reading.

    Feedback is one way, so contact support as well if you need an answer.
  </Accordion>
</AccordionGroup>

## FAQ

### Building a plan

<AccordionGroup>
  <Accordion title="How do I start a plan?">
    Three ways: the household's **Financial Planning** tab, the **Financial Planning** page, or **Ask Hazel** with the chat set to Financial Planning mode. A plain Ask chat will not start a plan. See [Getting started](/guides/financial-planning/overview/getting-started).
  </Accordion>

  <Accordion title="How much data do I need before I build?">
    The household's **Financial Planning** tab checks eight things: Accounts & Holdings, Calendar, Tax documents, Uploaded documents, Meetings & transcripts, CRM, Email and Business valuation. Business valuation only matters where a business does, so it can read Missing while the tab still says **Ready to build**.

    If something is short, the tab offers **Prepare data**, which uploads files and drafts a request email. Build anyway and the plan will say what it could not evidence.
  </Accordion>

  <Accordion title="Do I need to upload documents if my CRM is connected?">
    Yes. Neither CRM data nor custodian balances become planning figures. Statements, tax returns, policies and estate documents give a plan this household's specifics, and scans and photographs are fine. See [Documents and CRM data](/guides/financial-planning/your-data/documents-and-crm).
  </Accordion>

  <Accordion title="Can I see a finished plan without using client data?">
    Yes. The **Financial Planning** page offers **See financial plan example**, a complete plan on a made-up household, with **Take the tour** to walk you through the surface. It is read only, and carries no **Edit** and no PDF export.
  </Accordion>
</AccordionGroup>

### Working with a plan

<AccordionGroup>
  <Accordion title="Can a household have more than one plan?">
    Yes. A plan lives with the chat that built it, so a fresh build gives you a second plan rather than a new version of the first. Usually you want the new version: ask on the plan you have, or use **Regenerate** on the household's **Financial Planning** tab. For two different futures, ask for a scenario comparison inside one plan. See [Versions and regenerating](/guides/financial-planning/the-plan/versions-and-regenerating).
  </Accordion>

  <Accordion title="Where do I find a plan I built last week?">
    The **Financial Planning** page lists your plans, most recently worked on first, with the household, the **Status** and the persona applied. Selecting a row opens that household's **Financial Planning** tab; **Open chat** there reaches the plan's own conversation. **Draft in progress** means no version published yet.
  </Accordion>

  <Accordion title="Can I edit the text myself?">
    The prose, yes. Hover a passage, click the small pencil at its top right, make your change, then click away to stage it or press Escape to drop it. Staged changes collect in the bar at the bottom of the plan, and **Save** commits them as one new version.

    A number inside a sentence is a chip kept in sync with the plan. Rewrite the sentence around it if the wording is wrong; to move the number, change the assumption behind it or the data underneath.

    **Edit**, in the top bar of a plan in its own conversation, opens the conversation with Hazel about the plan rather than an editing mode. The household's **Financial Planning** tab carries no **Edit** button; **Open chat** there reaches the same conversation. See [Editing a plan directly](/guides/financial-planning/the-plan/editing-a-plan-directly).
  </Accordion>

  <Accordion title="Does regenerating keep my hand-edited text?">
    Usually. Hazel is asked to preserve still-valid analysis and the content you wrote, so a passage you rewrote normally comes through. Wording the new information has made untrue can still change. If a preference should hold on every plan, put it in your firm's [instructions](/guides/financial-planning/settings/personas/instructions).
  </Accordion>

  <Accordion title="How do I add a lever, or change a chart?">
    Both are requests in the plan's chat. For a lever, name the range, the step and the starting value: "Add a retirement-age lever from 60 to 70 in one-year steps, starting at 62." For a chart, name the point you want the client to take away rather than a chart type. See [Levers and scenarios](/guides/financial-planning/the-plan/levers-and-scenarios) and [How Hazel visualizes data](/guides/financial-planning/the-plan/how-hazel-visualizes-data).
  </Accordion>

  <Accordion title="Does the plan go to the client automatically?">
    No. Hazel never sends a plan to a client: you export the PDF and hand it over, or present the plan on screen. Your firm's disclaimer travels with both. See [Sharing and delivering](/guides/financial-planning/the-plan/sharing-and-delivering).
  </Accordion>
</AccordionGroup>

### Firm setup

<AccordionGroup>
  <Accordion title="Who can see Planning settings?">
    Firm owners only, and not firm admins; for everyone else the Planning tab does not appear. Every advisor still inherits what is set there, and can see it in the plan's **Appendix**. See [Access and availability](/guides/financial-planning/overview/access-and-availability).
  </Accordion>

  <Accordion title="How do I make a change apply to every plan?">
    Structure goes in [Plan design](/guides/financial-planning/plan-design/overview), voice and emphasis in [instructions](/guides/financial-planning/settings/personas/instructions), numbers in [Solver](/guides/financial-planning/assumptions/solver-assumptions) or [Market assumptions](/guides/financial-planning/assumptions/market-assumptions), and absolute rules in [Guardrails](/guides/financial-planning/assumptions/guardrails).
  </Accordion>

  <Accordion title="What happens if a module isn't in our layout?">
    A module is in your plans exactly while your layout carries it, so there is no on and off switch: add or remove one with **Design layout** from the **Plan design** card. Taking one out removes the **dedicated treatment** of that topic; broader sections still fold it in. See [Modules](/guides/financial-planning/plan-design/modules).
  </Accordion>

  <Accordion title="How many Client personas should we have?">
    Your firm starts with three that Hazel installs: HENRY, Pre-Retiree, and Retiree / Decumulator. Review, rename or edit them, and delete the ones that do not describe your book. Past that, enough for the client types you plan differently for.

    When no persona matches a household, Hazel builds on the base template alone and records None in **Applied settings**.
  </Accordion>

  <Accordion title="Can advisors change firm assumptions?">
    Not the firm defaults. In the plan's own conversation, the sliders button in the top bar opens **Plan settings**, which holds the fields meant to vary. The household's **Financial Planning** tab has no such button, so use **Open chat** there first.

    A value you set belongs to that plan, not the household, so a second plan for the same family keeps what it inherited. Each field prints the range Hazel accepts, a value outside it comes back with a message, and a reset control restores the inherited one. **Apply and replan** commits and recalculates.

    The advisory fee, the terminal heir tax rate and the number of simulations never vary, so the panel does not list them.
  </Accordion>

  <Accordion title="Why does this plan use a different success threshold than our firm standard?">
    Almost always because the matched persona overrides it on purpose. In the plan's **Appendix**, every value under **Applied settings** is labeled **Firm**, **Persona** or **This plan**, so you can see which layer set it.
  </Accordion>

  <Accordion title="Where do I set the disclaimer?">
    **Settings → Planning**, in the **Client disclaimer** card. It opens holding wording Hazel suggests, and nothing prints under a plan until your firm saves its own text. It saves as you type, and renders under every plan and in the PDF exactly as written. **Restore Hazel default** brings the suggested wording back.
  </Accordion>
</AccordionGroup>

## Where to go next

* [Best practices](/guides/financial-planning/best-practices)
* [Glossary](/guides/financial-planning/glossary)
* [Prompt library: Financial Planning](/resources/prompt-library/financial-planning)