Common Problems

Most Forge issues come from:

malformed schemas
inconsistent metadata
incorrect paths
missing Shape templates
configuration drift

The good news is that most problems are easy to diagnose once you know where Forge expects structure.

Validate Schema Says the Schema Is Missing Frontmatter

Your schema note must begin with a valid YAML frontmatter block.

Example:

---
type: reference
status: active
---

The body of the note must also include:

a version:: "..." line
a # Contract heading
one fenced YAML block beneath that heading

Example structure:

---
type: reference
status: active
---

version:: "1.0"

# Contract

```yaml
frontmatter:
  required: []
  optional: []

inline:
  allowed: []

ontology:
  relationships: {}

tag_rules:
  require_namespace: false
  unknown_tags: info
  severity: info
  allowed_namespaces: []

exempt_paths: []
```

Forge reads both the frontmatter and the YAML contract structure.

If either is malformed, schema validation can fail.

Vault Lint Finds Too Many Issues

This is normal for older or long-lived vaults.

Do not try to solve everything immediately.

Recommended approach:

disable strict mode initially
simplify the schema
start with a few stable fields
repair gradually

Good starter fields:

type
status
tags
created
updated

Most users should begin with lightweight consistency instead of heavy enforcement.

Forge works best as an incremental cleanup workflow.

Patch Says No Matching Files Found

Patch paths must be vault-relative and use forward slashes.

Good:

target_pattern: "Projects/**/*.md"

Risky:

target_pattern: "/Projects/**/*.md"

Common causes:

leading /
incorrect folder names
Windows-style backslashes
files outside the target scope
missing .md matches

If unsure, test against a smaller known folder first.

Patch Apply Changed Nothing

Open the dry-run details.

Common reasons include:

the value already existed
the note already matched the desired state
a when condition failed
only_if_missing skipped the operation
the target pattern matched no writable changes

Dry runs exist specifically to help diagnose these cases safely before changes are applied.

Export Ontology Index Says No Filter Is Configured

Go to:

Settings → Export

Then:

Enable export
Click Reload from schema
Select a filter field
Select at least one filter value

Common filter fields include:

type
status
domain

Forge uses these values to decide which note groups become relationship indexes.

Shape Lint Does Not Run

Check all of the following:

Shape Engine enabled
Shape heading validation enabled
Template folder contains:
```
Template, <shape>.md
```
Notes contain the configured type target field
Type values match Shape names exactly

Example:

type: project

expects:

Template, project.md

Shape matching is intentionally strict to avoid accidental cross-template validation.

Shape Repair Skips Files

Common skip reasons:

missing frontmatter
missing type target field
missing template
note already conforms
folder scope excludes the note
Shape Engine disabled

Run:

Forge: Run Shape Repair (Dry Run)

first to see which files would be affected and why others were skipped.

Installed Docs Did Not Update

The documentation installer skips files that already exist.

This protects:

local edits
annotations
customized examples
modified workflows

To reinstall a file:

rename or delete the installed copy
run:
```
Forge: Install Documentation
```
Forge installs the missing file again

Forge intentionally treats installed documentation as user-owned after installation.

Dataview or Bases Results Look Wrong

This is usually caused by inconsistent metadata rather than Forge itself.

Common examples:

project vs projects
active vs in-progress
malformed dates
inconsistent tags
missing fields

Recommended workflow:

Validate schema
Run Vault Lint
Normalize metadata
Repair inconsistencies
Re-run exports or dashboards

Forge helps keep metadata predictable so downstream tools remain reliable over time.

Shape Repair Reordered Headings Unexpectedly

Shape Repair uses recursive tree matching.

Forge evaluates:

heading text + heading level + parent chain

That means headings can move if they exist under the wrong structural parent.

This is intentional.

Always review dry runs before applying repairs broadly.

Recommended Recovery Strategy

If something feels wrong:

Stop and review the reports
Re-run dry runs instead of applying changes
Narrow the scope to a smaller folder
Simplify the schema or Shapes temporarily
Rebuild confidence gradually

Forge works best as a careful maintenance workflow, not a giant one-shot migration tool.