feat(skill): add troubleshooting reference; document .openlayerignore and the /v1 asymmetry - #26
Merged
Conversation
Dogfooding `openlayer init` against a real Next.js app surfaced three things the skill either got wrong or never mentioned. - New `references/troubleshooting.md`: a triage order and symptom tables for a setup that is already built and not working. `openlayer init`'s new "something went wrong" escape hatch hands its debug run to the agent with the skill installed, and that run needs one place to start from rather than per-topic tables scattered across six files. Its first instruction is to diagnose before editing — the failure mode we saw was correct instrumentation being rewritten while an unset env var survived. - Traced-function parameters must be JSON-serializable. `trace()` captures every declared parameter as an input variable, but a callback or client handle is dropped during serialization while its name stays in `inputVariableNames`, producing a 400 that names a column the user never meant to declare. Documented with the fix that keeps the trace intact. - `.openlayerignore` now has real coverage. It existed, was undocumented, and the only mention was a troubleshooting row advising users to "push from a clean dir" — advice that doesn't work when openlayer.json lives in an application root. Also records the `/v1` asymmetry between the SDK and CLI base URLs, which is what made a local backend fail silently. Minor version bump: new reference. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Part of OPEN-12148. Skills half of the fix; CLI half is openlayer-ai/openlayer-cli#46.
From @Vikas dogfooding
openlayer initagainst claude-quickstarts — Slack thread.initinstalls this skill and drives it, so these reach both onboarding tracks.New:
references/troubleshooting.mdA triage order and symptom tables for a setup that is already built and not working — "nothing arrives", API errors by status code, push/bundling failures, environment problems.
Two reasons it's its own reference rather than more rows in existing ones:
.env.openlayer— survived untouched.It also names some fixes as not-fixes: silencing a 400 by deleting the offending column, or wrapping the publish call in try/except, hide the failure rather than fixing it.
Traced parameters must be JSON-serializable
trace()captures every declared parameter of a traced function as an input variable. A callback, client handle, or DB session is dropped during serialization while its name stays ininputVariableNames, so the row arrives one column short of its config:This cost real debugging time and the skill said nothing about it. Now documented in
monitoring-instrumentation.mdwith the fix that keeps the trace intact — pass plain data, derive the non-serializable value inside the body — plus the Python equivalents (db_session,client,on_progress).The underlying SDK bug is OPEN-12149; this is the stopgap.
.openlayerignoreand the/v1asymmetry.openlayerignoreexisted, was undocumented, and the only mention anywhere was a troubleshooting row advising users to "push from a clean dir" — which doesn't work whenopenlayer.jsonlives in an application root. Replaced with real guidance incli.mdanddevelopment-setup.md, including the CLI's new defaults and the!dist/negation needed when an output or metrics directory shares a name with one.Also documented: SDK
OPENLAYER_BASE_URLincludes/v1, the CLI profile URL does not. That asymmetry made a local backend fail silently and is now stated wherever the variable appears.Versioning
0.3.0→0.4.0(minor: new reference), bumped in lockstep across all three manifests.python3 scripts/validate_skills.pypasses.🤖 Generated with Claude Code