Diagnosing Problems

When a memo does not look the way you expect, the cause is almost always one of a handful of known issues — and most are fixable by you, without waiting on engineering. This page is organized by symptom: find what you are seeing, read the likely cause, and follow the fix.

Tip

The single most useful diagnostic habit: when a section is thin, check what you uploaded before assuming the data does not exist. The most common failure mode in Memosa is a document that was uploaded but routed to the wrong bucket — which looks identical to “no document was uploaded” unless you check your upload history.

Symptom: a section is thin or generic

What you see: the market section, comparables, or financials reads shorter or vaguer than the deal warrants, or notes that evidence was limited.

Likely cause: the evidence that section needs never reached it. Each memo section has required source types — for example, the market and comparables sections depend on CoStar data; the financial section depends on the Excel model. If the required type is absent from what was retrieved, the section has little to work with.

What to do:

1. Confirm you uploaded the right document type for that section. Market and comps need CoStar exports; financials need the Excel model; sponsor and property narrative come from the PDF. See Supported Documents.
2. If you did upload it, suspect misclassification — not absence. CoStar reports are sometimes classified as generic PDFs at ingest, which leaves the CoStar-dependent sections empty even though the file is in the deal. The fix is to re-run with the document clearly identifiable as a CoStar export (a filename containing “CoStar” or the report type helps), or flag it so it routes correctly.
3. Re-generate. Memosa runs a section-aware recovery step that re-queries for a section’s required-but-missing source type, but recovery is a safety net — the durable fix is getting the right document classified correctly the first time.

Caution

“The market section is thin, so this deal must not have had CoStar data” is the wrong conclusion by default. Verify your upload history (Slack thread, web-chat files, or the Canvas documents list) first. A misclassified CoStar report shows up as zero CoStar evidence even though the file was uploaded. See Retrieval and Evidence.

Symptom: a number is different from my model

What you see: a figure in the memo (cap rate, NOI, IRR) does not match what you have in your spreadsheet or OM.

Likely cause, in order of probability:

1. A higher-precedence source won. Memosa resolves conflicts by a fixed order — your direct input beats Excel, Excel beats CoStar, CoStar beats PDF. If your OM PDF and your Excel model disagree, the Excel figure is authoritative and the memo uses it. This is working as designed.
2. A model cell was parsed differently than you read it. Spreadsheets encode the same number many ways (units, scale, a label in an unexpected place). If the winning source’s value is itself wrong, the parse is the thing to question.

What to do:

1. Open the Provenance panel in Canvas. For each resolved conflict it shows the winning source type and the candidates considered — so you can confirm whether the memo simply preferred a different source than you expected.
2. If the winning value is genuinely wrong, the issue is in how that source was parsed. Re-check the cell in your Excel model, and if it is correct there but wrong in the memo, this is a parsing issue worth reporting. See Document Processing for how models are read.

Note

A [1]-style footnote on the figure points to the exact source it came from. Following the citation is the fastest way to see whether the memo is citing the source you think it is.

Symptom: the readiness score looks stale or wrong

What you see: the document readiness score or grade does not reflect edits you just made, or flags a section you already fixed.

Likely cause: readiness is an aggregate score that is cached briefly for performance. It combines section quality, completeness, approval state, and freshness, and refreshes on a short interval rather than on every keystroke.

What to do:

1. Give it a moment, then refresh. The score recomputes shortly after changes; a manual refresh forces it immediately.
2. Check which dimension is dragging the score. Readiness identifies the weakest, stalest, and missing sections — fix what it points to rather than guessing. See Quality and Readiness.

Symptom: comparables look wrong or sparse

What you see: the comps in the memo seem off — too few, or properties that are not truly comparable.

Likely cause: comps are selected by typed constraints, not loose similarity. A property must be in the same compatibility group (multifamily to multifamily, etc.), within ±50% size, and within ±10 years of vintage. This deliberately excludes near-misses — which is usually what you want, but it means a deal in a thin submarket can legitimately have few qualifying comps.

What to do:

1. Open the Comp filters tab in Canvas. It shows the exact constraints the comparables agent used and the comps that passed. If a comp you expected is missing, the filters tell you why (wrong band, different class).
2. Confirm the subject property’s attributes parsed correctly. Comps are matched against the subject’s extracted size, vintage, and asset class — if those parsed wrong, the comp set will be off. See Cross-Deal Intelligence.

Symptom: generation seems stuck

What you see: a memo has been “generating” for a long time with no completion.

Likely cause: a normal full generation takes 15–25 minutes; document ingest takes 2–5 minutes before that. Most “stuck” reports are simply a run still in progress.

What to do:

1. Watch the progress stream. Web-chat intake streams live progress; Slack posts updates in-thread. A run that is still emitting progress is healthy.
2. If it genuinely hangs, Memosa auto-reclaims runs that exceed their headroom (4 hours for generation, 20 minutes for ingest) and surfaces an error so the conversation is not pinned forever. At that point, retry. See Known Limits and Errors.

Symptom: an export is blocked

What you see: you try to generate an Investor Packet and it does not produce a file.

Likely cause: Investor Packet and OMCMS exports require the document to be in the APPROVED state. If the document is still in DRAFT or EDITING, the export is intentionally blocked with a clear “document not approved” message.

What to do: approve the document, then retry. Approval is reversible — you can reopen to EDITING afterward. See The Approval Gate and Document Lifecycle.

When a fallback fires, it is still a bug worth reporting

Caution

Memosa is resilient: when a primary path fails, it falls back to a degraded path so you still get output. But a fallback firing means the primary path had a problem, and fallback output is lower quality than the primary path would have produced. If you can tell a section was generated from a degraded path (thin evidence, a “limited data” note), that is worth flagging — the resilient catch does not make the underlying cause “fine.” Capture the deal name and what you uploaded so it can be investigated.

Sources

• src/utils/consolidated_retrieval/recovery/source_type_recovery.py — section-aware required/optional source types (SECTION_EXPECTED_TYPES), Stage B recovery behavior.
• src/canvas/services/web_intake_config.py — processing_stale_secs / generating_memo_stale_secs (the stuck-run reclamation thresholds).
• src/canvas/routes/comparables_trail_routes.py — comp constraint defaults (size/vintage band) surfaced in the Comp filters tab.
• src/intel/readiness/readiness_service.py — document readiness scoring (cached, multi-dimension).
• src/investor_packet/generation_validator.py — export gating on APPROVED.
• Native memory: costar_classification_silent_misclassify.md (misclassified CoStar = looks identical to absence), feedback_fallback_is_still_bug.md (a fallback firing is a primary-path bug).