Troubleshooting

Quick fixes for common issues.

MkDocs build errors

mapping values are not allowed here (mkdocs.yml)

• Cause: Mis-indentation or mixed tabs/spaces in mkdocs.yml.
• Fix: Use 2 spaces per indentation level. Ensure subsections like Programs → Implementation are properly nested.

expected , but found '-'

• Cause: A list item is placed where a map value is expected (indent is off).
• Fix: Align the - Label: path.md lines under the correct parent key.

Missing image warnings

• Example: target 'assets/programs/...png' is not found among documentation files.
• Fixes:
  • Add the referenced image under docs/assets/....
  • Or correct the relative path in the Markdown.

Unrecognized relative link

• Example: Did you mean '../inventory/index.md'?
• Fix: Point overview links to index.md explicitly.

Windows tips

• If mkdocs serve fails, check that Python and mkdocs are installed and on PATH.
• Use a single PowerShell line with ; to chain commands when needed.
• Some antivirus tools may lock files in site/; retry the build after a few seconds.

Dashboards show no data

• Clear both global and local filters and click Apply.
• Verify your permissions; some charts are role-gated.
• Check date ranges: too narrow windows can hide data.

Residence Status shows "No data"

• The chart uses row-level fallbacks. Clear filters to render unfiltered first, then refine.

Indicator exports: columns

• Target and Quarterly Target are adjacent. If a column is missing, update to the latest build.

Messenger: Delete chat history

• Use the 3-dots menu on a person to delete the conversation (soft-delete). Groups are unaffected.

Attendance visibility

• Ensure the employee has an active contract overlapping the selected date window.

Leave balances look incorrect

• Ensure accrual/carry-over rules are configured correctly for your profile (Annual/Sick only).