Troubleshooting

Search this page for the symptom you’re seeing. Most issues fall under one of these ten domains; each section is grouped symptom → cause → fix → when to escalate.

Before you read on

The single most common Fola issue is the org being on the demo plan when the user thinks they’re on a paid tier. Open /workspace/settings/billing and confirm the “Current plan” card. Demo orgs are hard-capped (no overage) and cannot exceed their monthly AI allotment.

Billing, subscriptions, and Square

”no active subscription” on plan-switch (HTTP 409)

Cause: You’re on the DEMO plan and clicked a paid-plan card. DEMO orgs have no org_subscription row, so the /change-plan endpoint refuses.

Fix: Newer builds of the workspace route DEMO upgrades through /subscribe automatically. If you still see this error, hard-refresh the billing page. If it persists, email founder@folaform.com with your org name.

”firm_service_agreement_required” on subscribe (HTTP 409)

Cause: You haven’t signed the Fola service agreement yet. Required on the FIRST paid subscription.

Fix: Open /workspace/settings/agreement, review (optionally download the unsigned PDF for legal team review), attest authority-to-bind, draw your signature, click Sign. Then retry the upgrade.

Auto-charge failed; subscription PAST_DUE

Cause: Square rejected the saved card. Three failed retries every 72h flip the subscription to PAST_DUE.

Fix:

1. Open Settings → Billing → Payment method, save a new card.
2. The next retry sweep (hourly) charges automatically.
3. To force-retry now, click Pay now on the open invoice.

Escalate to billing@folaform.com if the card declines with a generic error or if Square’s reason text is unclear.

Overage on the invoice but my members were within budget

Cause: The pool counter ticks on ANY run that exceeds the firm-pool cap, even if individual per-member budgets weren’t exceeded. Pool + per-member are independent — both can be exceeded separately.

Fix: Open Settings → AI insights to see the per-member breakdown for the cycle. If the numbers genuinely don’t match your invoice, email billing@folaform.com — we re-run the cycle’s accrual on request.

Chargeback initiated → account suspended

Cause: Initiating a chargeback against a Fola charge is prohibited under Section 22 of the service agreement. Suspends the account automatically + forfeits any pending refund.

Fix: Resolve the dispute directly. Reach out to founder@folaform.com — we fix billing errors faster than your card issuer can.

---

AI features (Ask Fola, Autofill, Review, Mandamus)

“Demo limit reached” modal won’t dismiss

Cause: You’ve used your DEMO month’s AI cap (5 chats / 2 autofills / 2 reviews per seat). DEMO is hard-capped; there’s no overage path.

Fix: Upgrade at Settings → Billing. Or wait for the calendar month to roll over — caps reset on the 1st.

Ask Fola says “couldn’t find your profile”

Cause: The active client binding on your chat session points at a profile you no longer have access to (e.g. archived client, role demotion).

Fix: Click the client-picker at the top of the chat and pick a visible client. Ask Fola will reset its active context to the new selection.

AI Autofill output is wrong on a specific field

Cause: Either the profile field is empty / wrong for that client, or the form definition’s pdfMapping mis-routes the field.

Fix:

1. Open the client’s profile and confirm the source field.
2. If the source is correct, the renderer is wrong. Email forms@folaform.com with the form ID + field name + a screenshot of the wrong output.

AI Review took >10 minutes and never finished

Cause: Anthropic API outage, or the form draft is unusually large (>200 pages of supporting evidence).

Fix: Open Settings → AI insights and look for failed AI runs in the last hour. If the failure repeats, the run is stuck; cancel via the chat surface and retry. Escalate to founder@folaform.com if 3+ reviews fail in a row.

402 Payment Required on a chat send

Cause: Your firm exceeded its pooled AI Chat cap AND has no card on file to pay overage.

Fix:

• DEMO org: upgrade.
• Paid org: add a card under Settings → Billing, or top up the org’s account balance, then retry the send.

Ask Fola hallucinated a value (A-number, address, SSN)

Fix: Fola is instructed never to fabricate values. If you see one, that’s a P0 bug — email founder@folaform.com with the chat run ID (visible at the top of the chat surface). We pull the agent’s tool log for forensic review.

---

Forms (filling, rendering, PDFs)

A field is blank that I filled in

Cause: The form definition’s pdfMapping either skipped that field or maps to a different AcroForm widget than expected.

Fix: Email forms@folaform.com with:

• The form ID (e.g. i-130)
• The exact field label that’s blank
• A screenshot of the filled value in the profile vs. the blank in the PDF

We re-author the YAML mapping and ship a fix the same day if it’s a real misrouting.

PDF still has the COPY watermark after I finalized

Cause: Watermark removal only happens at complete_draft on an entitled user. If you finalized a form you don’t have access to, or your tier doesn’t unlock that form, the watermark stays.

Fix: Confirm the form is unlocked at My Forms → [form]. If unlocked and the watermark is still there, hard-refresh and re-export. Persistent watermark = email forms@folaform.com.

USCIS rejected my filing

Cause: Wrong filing fee, missing signature, wrong filing location, expired form edition, or missing G-28.

Fix:

1. Read the USCIS rejection notice for the specific reason.
2. Open Ask Fola and paste the rejection text — Fola will identify what needs to change.
3. Correct + refile. If the rejection is for an expired form edition, email forms@folaform.com so we update the bundled template.

Form catalog doesn’t show the form I need

Cause: Not all forms are in the catalog yet. We add ~10/month.

Fix: Search the catalog by both form ID and human title. If still absent, email forms@folaform.com with the form ID — most requested forms ship within 30 days.

Checkbox group is all-checked or none-checked

Cause: The form’s enum→boolean fanout in the YAML doesn’t match the actual PDF widget export letters.

Fix: This is a renderer bug. Email forms@folaform.com with the form ID + which question is broken; we typically ship a YAML fix within 24h.

Translation overlay shows English, not the localized text

Cause: Translation overlay for that language isn’t authored for that specific form yet.

Fix: Switch to the form’s PDF in English (still legally valid) and email forms@folaform.com to request the missing translation overlay.

---

Clients and profiles

Client doesn’t appear in my list

Cause: Filter active (Archive / Has email / Missing email tabs), the client is archived, or your role doesn’t have visibility.

Fix: Click All clients to clear filters. If still missing, check Settings → Members → [your row] to confirm your role + access scope. Archived clients live under the Archive tab.

Intake link returns 404

Cause: The link was already used (one-time-use) or expired.

Fix: From the client’s profile, click Generate new intake link. Old links are invalidated when a new one is generated.

I uploaded a document but it’s not in the Documents tab

Cause: Upload failed (size limit ~25 MB; check browser console for 413) or you’re looking at the wrong client.

Fix: Confirm the active client in the breadcrumb. Re-upload smaller files. For large evidence packets, split into less than 25 MB chunks.

Client search returns nothing

Cause: Search is scoped to client name + email by default. SSN / A-number / passport number aren’t searchable surfaces.

Fix: Type the client’s first or last name into the top-bar search. For A-number lookups, open the form catalog and search there instead.

Family member sub-profile not flowing into forms

Cause: The sub-profile exists but isn’t marked as the right kind of relation (spouse vs. derivative vs. parent).

Fix: Open the main client → Family section → click the sub-profile → confirm the “Relationship” dropdown is correct. The form mapping pulls by relationship type.

---

Documents and PDFs

”Upload failed — file too large”

Cause: Hard limit ~25 MB per file in Supabase blob storage.

Fix: Split the file. For multi-page scans, use a tool like pdftk or Adobe Acrobat to extract page ranges into separate PDFs.

PDF asks for a password I don’t have

Cause: Your firm’s PDF lock is enabled at Settings → PDF protection. Every Fola-generated PDF is encrypted with that password.

Fix: Ask an ORG_OWNER or ORG_ADMIN for the current password. The password can be rotated but not recovered if lost — the old PDFs keep their old password.

Extracted text is garbled / wrong language

Cause: OCR ran on a low-resolution scan, or the source PDF embeds text in a non-Unicode encoding.

Fix: Re-scan at ≥300 DPI. If the source is already high-res, the PDF’s text layer is corrupted; convert it to image-PDF first, then upload — OCR re-extracts cleanly.

Old PDFs require old password, new ones need new

Cause: Expected behavior. Rotating the PDF-lock password doesn’t re-encrypt existing PDFs — they keep their original password until re-rendered.

Fix: To roll a single old PDF onto the new password, re-render it from the source form. To re-roll en-masse, email founder@folaform.com — we can run a bulk re-encrypt job.

Letterhead logo is blurry on print

Cause: Org logo uploaded at low resolution.

Fix: Re-upload at ≥256×256 (preferably 1024+) under Settings → Organization → Logo. SVG is the safest; PNG works if the source is high-DPI. Confirm by printing a test cover letter at 100% scale.

---

Members and access

Invite email didn’t arrive

Cause: Spam filter, typo in the address, or invite expired (7-day TTL).

Fix:

1. Confirm the email under Settings → Members.
2. Ask the invitee to check Spam / Promotions.
3. Resend by clicking Resend invite on their row.

I demoted someone but they still see admin pages

Cause: Their JWT still carries the old role until they log out and back in. Sessions can be up to 30 days.

Fix: Force-sign-out — open Settings → Members → [their row] → Revoke active sessions. They’ll need to re-login with the new role.

Per-member budget set but member can still exceed it

Cause: “Allow overage” is enabled for that member. Per-member cap is soft when allow-overage is on; the run goes through and the firm pays the overage rate.

Fix: Open Settings → Usage budgets → [their row] and toggle Allow overage off. Then the cap is a hard ceiling.

Can’t transfer org ownership

Cause: The target user is not in the org yet, or is on a non-org role (SOLO / END_CLIENT).

Fix: Invite the target as ORG_ADMIN first; they accept; THEN initiate transfer. Both parties confirm via separate email links.

---

USCIS-side issues

Receipt number doesn’t track on USPS or USCIS

Cause: USCIS hasn’t ingested the filing yet (typically 1-2 weeks after USPS delivery confirmation), or the receipt number was typo’d.

Fix: Verify the receipt number against the official paper receipt notice. For e-filed cases, the receipt is generated instantly; for paper-filed, allow 2 weeks.

USPS shows delivered but no receipt notice has arrived

Fix: This is normal for the first 30-45 days. USCIS opens packets in mailroom order; backlog is typical. If 60+ days have passed with no receipt notice, file a case inquiry with USCIS (Fola can generate the inquiry letter — ask Fola in chat).

Case status hasn’t updated in 6+ months past normal processing

Cause: Unreasonable delay — eligible for a federal-court mandamus suit.

Fix: Open Ask Fola and type generate mandamus for {client}. Fola will produce a complete federal-court complaint packet covering the delay. $79 per mandamus generation; not covered by demo plan.

Biometrics no-show

Cause: Client missed the ASC appointment.

Fix: File Form I-797C reschedule request (Fola can draft it). USCIS typically grants one reschedule; second no-shows risk denial.

---

Email and templates

Client didn’t receive the intake email

Cause: Spam folder, address typo, or firm domain reputation is fresh (new domains are spam-flagged by default).

Fix:

1. Ask the client to check Spam / Promotions / All Mail.
2. Verify the email address under Clients → [client] → Profile.
3. For domain reputation issues, set up SPF + DKIM for your firm domain at Settings → Organization → Email settings.

Template substitution didn’t fire — saw literal {{var}}

Cause: Variable name mismatch — the template uses {{first_name}} but the substitution context provides firstName.

Fix: Open Settings → Email templates → [template] and confirm the variable names match exactly. Substitution is case-sensitive.

Email shows wrong from-name

Cause: The template’s from-name is set to a static value; doesn’t inherit from org.

Fix: Open the template → edit the From name field. Use {{org_name}} to pull the org’s display name dynamically.

---

API and SDK

401 Unauthorized on every API request

Cause: Expired JWT or wrong API key.

Fix:

• For workspace-issued JWTs: log in to the workspace to refresh the token, then re-grab from localStorage.fola_token.
• For API keys: regenerate under Settings → API keys. The old key is revoked immediately.

429 Too Many Requests under the cap

Cause: You’re being rate-limited by IP, not by key. The 60/min cap is per-key; the 600/hour cap is per-org.

Fix: Spread requests across multiple keys, or back off exponentially per the Retry-After header.

Webhook signature verification fails

Cause: You’re verifying against the wrong secret, or the body has been altered between Fola and your endpoint (e.g. body-parsing middleware re-stringifies).

Fix: Verify against the RAW request body (before any JSON parse). HMAC payload is <timestamp>.<raw-body>. Use the secret shown at the moment of webhook creation; rotate it via Settings → Webhooks → [row] → Rotate secret if compromised.

Webhook never fires

Cause: Webhook is disabled, or your endpoint returned a non-2xx on the first 3 retries and Fola gave up.

Fix: Open Settings → Webhooks and check the Last delivery status column. If “disabled”, re-enable. If “permanent failure”, fix your endpoint and click Replay.

---

Service agreement, branding, and PDF lock

”Duplicate key value violates unique constraint” on publishing a new agreement version

Cause: Two simultaneous publish attempts, OR a publish that fired before the prior active row was flipped off.

Fix: Already fixed in commit a73d50f — the publish path now flips the prior active row off first, then inserts the new one. Re-deploy or wait for the next backend rollout.

Signed agreement PDF won’t render

Cause: The deferred PDF render after the sign tx failed (Supabase blob upload error or PDFBox crash on the markdown source).

Fix: From Settings → Service agreement, click Download my copy — Fola will render on-demand if the stored PDF is missing. Persistent failures: email founder@folaform.com with the agreement ID.

Letterhead shows wrong firm name

Cause: legal_name on the platform_billing_settings row or the org row is stale.

Fix: Under Settings → Organization, edit Display name + Legal name. The change propagates to every newly-rendered PDF.

PDF lock password lost

Cause: Passwords are salted and hashed; not recoverable.

Fix: Set a new password at Settings → PDF protection. NEW PDFs will use the new password; OLD PDFs are still encrypted with the lost old password. To recover the old PDFs, email founder@folaform.com — we can run a bulk re-encrypt against the old hash if you can prove ownership.

---

Account and authentication

Can’t log in, no error shown

Cause: Browser blocked third-party cookies (we use them for the Supabase auth flow).

Fix: Enable third-party cookies for folaform.com. In Safari this also requires turning off Prevent Cross-Site Tracking for the session.

”Email not verified” but I clicked the link

Cause: Verification link expired (24h TTL) or you clicked it on a different device than where you signed up.

Fix: On the login screen, click Resend verification email. Click the new link in the same browser you signed up with.

Password reset email never arrived

Cause: Same as the “intake email didn’t arrive” reason above — spam, typo, or domain reputation.

Fix: Check Spam / Promotions. Resend at /login → Forgot password.

Session expired mid-form-fill — did I lose my work?

Cause: Sessions are 30-day-idle. If you somehow lost the session, re-login.

Fix: Drafts are auto-saved every 5 seconds. Your in-progress work is preserved on the server. Re-open the form and the draft is restored automatically.

---

Still stuck?

If your error doesn’t appear here:

• First-line: email support@folaform.com. Reply within 24 business hours.
• Billing-specific: billing@folaform.com.
• Forms / renderer / YAML issues: forms@folaform.com.
• Security incident / data leak / chargeback dispute / urgent business issue: founder@folaform.com. Read within 24 hours including weekends.

When you write in, please include:

1. Your org name + your email
2. The error message verbatim (screenshot is best)
3. The form ID / client name / invoice number — whatever’s relevant
4. Approximate time of the failure in your local timezone