Repository navigation
docs(troubleshooting): quote real error messages and fix wrong remediations - #3812
Merged
Merged
Conversation
Daniel Meppiel (danielmeppiel)
requested a review
from Sergio Sisternes (sergio-sisternes-epam)
as a code owner
November 17, 2026 20:45
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The documentation incorrectly promises automatic cleanup of stale generated files and recommends apm install --update for a ref mismatch that only requires apm install.
2 open issues
What changed in this PR
This docs-only PR updates APM troubleshooting guidance as part of the documentation re-sweep in #3800, aligning quoted errors and recovery steps with current CLI behavior.
Changes:
- Updates policy discovery, cache refresh, and policy-violation examples.
- Clarifies migration steps and separates compile outputs from install-deployed files.
- Corrects common error messages, command hints, and configuration references.
| File | Description |
|---|---|
docs/src/content/docs/troubleshooting/policy-debugging.md |
Updates policy discovery, symptoms, remediation commands, and a broken anchor. |
docs/src/content/docs/troubleshooting/migration.md |
Revises lockfile, compile-strategy, target-removal, and MCP migration guidance. |
docs/src/content/docs/troubleshooting/compile-zero-output-warning.md |
Distinguishes compile output from prompt and skill deployment. |
docs/src/content/docs/troubleshooting/common-errors.md |
Updates error examples and troubleshooting commands. |
Review effort: Balanced
…ations Surgical fixes from the post-0.36 docs corpus re-sweep. Every changed claim was checked against current main (CLI --help, source, or a scratch-dir run). Pages that a still-open PR edits are left out, per the approved scope. Refs #3800 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel)
force-pushed
the
docs-sweep/troubleshooting
branch
from
November 17, 2026 21:01
2e32311 to
56c3867
Compare
Daniel Meppiel (danielmeppiel)
deleted the
docs-sweep/troubleshooting
branch
November 18, 2026 02:57
This was referenced Nov 18, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Description
Surgical fixes to
troubleshooting/*. Every quoted message was grepped insrc/apm_cli/, and every remediation was checked against--help, the code, or a scratch run.policy-debugging.md: five quoted symptom strings do not exist in the code, so they now quote the real messages.apm install mcp:<name>is nowapm install --mcp <name>. Discovery no longer lists a projectapm.ymlstep and instead names the.github-private/.github/.apm/_apmcascade. To test against upstream, pass--policy-source <owner>/.github(orgresolves to your fork). Use--no-cacheto refetch the policy, since--refreshdoes not touch it. Also fixes a dead#merge-rules-tighten-onlyanchor.migration.md:apm prunedoes not remove a dropped target's files (apm installdoes) and does not switch compile strategies (compilation.strategyplusapm compile --clean, then remove leftover nested files by hand when moving tosingle-file). Also corrects the unsupported-lockfile-version message, notes that MCP servers belong underdependencies.mcp, and lists compile's real outputs.compile-zero-output-warning.md: the worked examples confused compile and install output. Command files and skills come fromapm install. The*_files_writtenstats keys are not printed.common-errors.md: corrects the "No primitives matched", unapproved-host and authentication-failure messages and their fixes. The ref-mismatch hint depends on the case (apm install --updatefor a missing lock entry,apm installfor a changed ref).apm listlists scripts, not prompts. The policy pin ispolicy.hashinapm.yml. Timeouts are no longer quoted as fixed numbers.Deferred to the sweep report (they need a rewrite or a decision): the section 1 failure sample in policy-debugging and the nonexistent per-dependency
includes:filter in compile-zero-output-warning step 3.Pages that a still-open PR also edits are left out of this PR, as the approved scope requires. Their fixes are held for after those PRs land, and the sweep report lists them.
Issue and approved scope
Issue: Refs #3800
Human scope-approval comment: #3800 (comment)
Does this PR complete the issue, or what remains? Partial: one area batch of the corpus re-sweep. Pages edited by still-open PRs are not touched here; their findings are recorded in the final sweep report and re-checked after v0.36.1.
Type of change
Testing
.venv/bin/apm <cmd> --help, the source undersrc/apm_cli/, or a scratch-directory run.cd docs && npm run buildexits 0 ("All internal links are valid"; "Checked 1197 relative link(s) ... No broken relative links found").Spec conformance (OpenAPM v0.1)