Appendix B: Troubleshooting and FAQs
Objectives
By the end of this appendix you will be able to:
- Diagnose common AL development failures faster
- Use a repeatable debug checklist before changing code
- Classify errors by layer (environment, compile, runtime, data)
- Apply issue-resolution habits that improve contribution quality
B.1 Debug checklist (use in order)
- Environment check: the AL extension for VS Code is installed, symbols are downloaded, and the sandbox is reachable.
- Compile check: resolve the first error in the output before chasing the errors that follow from it.
- Repro check: reproduce the problem with the fewest steps and known sample data.
- Boundary check: inspect each transition from page action to codeunit to table trigger.
- Data check: verify key fields and your assumptions about prior state (
xRec). - Regression check: add or run tests for the fixed behavior (Chapter 14).
B.2 Common error catalog
| Error symptom | Likely cause | First fix step |
|---|---|---|
Table ... not found | Missing symbol reference or wrong object ID/range | Re-download symbols and verify object metadata |
The record already exists | Duplicate key on insert | Validate key design and duplicate guards |
You do not have permission ... | Missing permission set grants | Review Chapter 11/15 permission setup |
Runtime cannot be changed unexpectedly | Trigger checks current state (Rec) instead of prior state (xRec) | Correct trigger logic and add regression test |
| API call fails with non-success status | Remote endpoint/auth/contract mismatch | Log status code and validate request contract |
B.3 FAQ
How do I know whether logic belongs in a page trigger or codeunit?
Put reusable business rules in a codeunit and call them from page actions. Keep page code thin (Chapters 8 and 9).
Why does my trigger block valid edits?
Check whether your rule needs the pre-change state (xRec) instead of the current state (Rec) in OnModify.
When should I add tests?
Right after you add or fix business logic, and especially after a bug fix that could regress (Chapter 14).
B.4 Escalation notes for contributors
When you open an issue or PR, include minimal repro steps, the observed and expected behavior, a link to the affected chapter or object, and evidence that you validated the change.
Appendix summary
You now have a practical troubleshooting sequence, and you can quickly map common errors to their likely causes. You can also package technical findings clearly so others can work with them.
Tasks
- Checklist run. Apply B.1 to one recent issue you encountered.
- Error mapping. Add one new row to the error catalog from your own experience.
- Try it yourself. Write a minimal repro template for future chapter bugs.
Check your work: your troubleshooting notes should be detailed enough for another contributor to reproduce and validate your fix.