Skip to content
Veckl Docs

Troubleshooting

Start with the error shown in the UI or terminal. Most Veckl setup problems come from GitHub credentials, OAuth callback URLs, or missing repository files.

verify-env Reports Missing Variables

Section titled “verify-env Reports Missing Variables”

Run:

Terminal window
./scripts/verify-env.sh .env

If a value is reported as missing or a placeholder, replace it in .env. Values like <your-github-app-id> are placeholders and will fail validation.

Session Key Validation Fails

Section titled “Session Key Validation Fails”

Generate new keys:

Terminal window
./scripts/generate-session-keys.sh

Each session key must be base64 and decode to exactly 32 bytes.

Sign-In Redirects to the Wrong Port

Section titled “Sign-In Redirects to the Wrong Port”

For local development, the OAuth callback URL must be:

http://localhost:3000/auth/github/callback

Update the OAuth App settings and confirm GITHUB_OAUTH_REDIRECT_URL matches.

Cannot Load Test Cases

Section titled “Cannot Load Test Cases”

Check:

  • The GitHub App is installed on the target repository.
  • The app has contents read/write permission.
  • GITHUB_OWNER, GITHUB_REPO, and GITHUB_BRANCH point to the right location.
  • The branch exists.
  • The repository has been initialized from the Admin screen.

Use Admin > Test Connection to confirm repository access.

Repository Needs Initialization

Section titled “Repository Needs Initialization”

Open Admin and select Initialize Repository.

Veckl creates missing starter files but does not overwrite existing files.

Catalog Is Empty

Section titled “Catalog Is Empty”

Open Admin > Catalog.

For connected environments, use Preview then Commit Import.

For disconnected environments, upload a Veckl catalog export, raw OSCAL JSON catalog, or existing config/catalog.json.

Component Is Not Available When Creating a Test

Section titled “Component Is Not Available When Creating a Test”

Open Admin > Components and add the component. Component codes are case-sensitive and should be short uppercase identifiers.

Draft Cannot Be Executed

Section titled “Draft Cannot Be Executed”

Publish the draft first. Only active test cases can be executed.

Kubernetes Pod Fails to Start

Section titled “Kubernetes Pod Fails to Start”

Check:

  • The veckl-secrets Secret exists in the veckl namespace.
  • Required secret values are populated.
  • The private key is mounted where GITHUB_APP_PRIVATE_KEY_PATH points.
  • The backend can reach GitHub or GHES.
  • GHES private CA bundles are mounted and referenced by GITHUB_CA_BUNDLE_PATH.

Frontend Cannot Reach Backend

Section titled “Frontend Cannot Reach Backend”

In local development, make dev sets the frontend API base URL for you.

In Kubernetes, confirm the Ingress path routing and both services:

Terminal window
kubectl get svc -n veckl
kubectl get ingress -n veckl

Without Ingress, port-forward the frontend service and open http://localhost:3000.