> For the complete documentation index, see [llms.txt](https://codifi-fdm.gitbook.io/codifi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codifi-fdm.gitbook.io/codifi-docs/known-issues-and-edge-cases/known-issues.md).

# About Known Issues

A structured catalog of things in Codifi that are **known to behave in a surprising way**, **broken and not yet fixed**, or **recently resolved but still worth documenting** because users continue to hit them.

> If you're trying to **do something** and it isn't working, start with the [**FAQ**](/codifi-docs/frequently-asked-questions/faq.md). If you've confirmed the behavior is unexpected or a bug, that's when this section helps.

## How issues are classified

Every issue has a **status** in its page header:

| Status            | What it means                                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 🟡 **open**       | Confirmed issue with no reliable workaround yet. We're tracking it.                                                         |
| 🟢 **workaround** | A documented manual workaround exists. The page tells you exactly what to do.                                               |
| ✅ **resolved**    | Fixed in a specific release. The page stays published so people searching the symptom can confirm they don't need to worry. |

And a **severity**:

| Severity       | What it means                                             |
| -------------- | --------------------------------------------------------- |
| 🛑 **blocker** | Blocks core workflows; no reasonable way to work around.  |
| 🔶 **major**   | Substantially impacts a workflow but a workaround exists. |
| 🔷 **minor**   | Cosmetic, edge-case, or affects very few users.           |

## Browse

* [**Open Issues**](https://gitlab.com/codifilab/codifi-docs/-/tree/gitbook/known-issues/open/README.md) — known but no workaround documented yet
* [**Issues with Workarounds**](https://gitlab.com/codifilab/codifi-docs/-/tree/gitbook/known-issues/workaround/README.md) — known with a documented workaround
* [**Resolved**](https://gitlab.com/codifilab/codifi-docs/-/tree/gitbook/known-issues/resolved/README.md) — fixed in a specific release

## Recent additions

* ✅ [Projects with several raster overlays crash the app or fill device storage](/codifi-docs/known-issues-and-edge-cases/known-issues/raster-overlays-crash-or-fill-storage.md) — blocker · resolved in v3.3
* ✅ [HEIC photos render as "Image cannot be loaded" in reports](/codifi-docs/known-issues-and-edge-cases/known-issues/heic-photos-fail-in-reports.md) — major · resolved in v3.3
* 🟢 [Photos appear pixelated or low-quality](/codifi-docs/known-issues-and-edge-cases/known-issues/photos-appear-pixelated.md) — minor · workaround documented

> Resolved issues stay published rather than being deleted, so that anyone searching the symptom still lands on an explanation and learns which release fixed it.

## How to report an issue worth documenting here

If you've hit something that you think belongs in Known Issues:

1. **Try the** [**FAQ**](/codifi-docs/frequently-asked-questions/faq.md) **and the relevant feature page first.**
2. **Search this section** — your issue might already be here.
3. **Report it** via:
   * **Slack**: `#codifi-support` — describe the symptom, what you were doing, and how to reproduce. If support confirms it's "a known limitation" or gives you a "here's the workaround," that's a strong KI candidate.
   * **Email**: <support@codifi.com> — same info.
   * **Direct PR** (internal team): copy [`_template.md`](https://gitlab.com/codifilab/codifi-docs/-/tree/gitbook/known-issues/_template.md) into the appropriate status folder and fill it in. Open a PR for the docs team to review.

## How we decide what gets a Known Issue page

We promote an item to a Known Issue page when:

* It's been hit by **at least two distinct Projects** (so it's not a one-off configuration mistake).
* It's **reproducible** — we can describe what triggers it.
* It's **audience-safe** — wording doesn't reveal customer PII or unannounced features.

Items that don't meet promotion criteria become Linear tickets only, and don't get a public page.

## How we keep this honest

* **Quarterly review.** We re-test every `open` issue to see if it's silently been fixed, and we sweep `resolved` issues older than 6 months to the archive if traffic has dropped.
* **Resolved issues stay published.** Users Google a symptom for years after a fix ships. Removing a page makes someone re-discover the problem from scratch.
* **Keywords are aggressive.** Every page has a `keywords:` frontmatter field with all the phrasings a user might type — pixelated, blurry, fuzzy, low quality, low res, bad photo. Search ranks them all together.