PenstockGuide / Plans, privacy and help
Troubleshooting
Fixes for the problems people meet most, by symptom. Most come down to an untrusted project, a setting that is not where Penstock looks, or an engine that answered with an error.
First, run the doctor
The doctor prints the settings files that apply, the engine, the profiles, and whether the engine answers. Most problems show up right there.
Run the doctor
JetBrains
Right-click in the Penstock tool window and choose Run Penstock | Doctor.
VS Code
Choose Run Penstock | Doctor in the Penstock view, or run penstock doctor in the terminal.
Command line
penstock doctorpenstock doctor --format json prints the settings that apply after every layer.
Problems that depend on your tool
A blank editor, a file that opens as plain text, a command that will not start: these depend on the tool you use.
Problems in your tool
Check and lint findings do not appear
| No markers on the canvas | The linting button on the canvas turns them off and on. It is hidden while token simulation runs. The findings are in the Problems tab of the sidebar, under Rules. |
| "The bpmnlint rules could not run" | Your .bpmnlintrc uses a bpmnlint plugin. The editor loads plugin rules only from a bundle named by lint.clientBundlePath. See Validation. |
| My own rules are ignored | lint.configPath is relative to the project root. penstock doctor prints the path and says if it is missing. |
Deployment fails
A deployment the engine refuses says which files it refused and why, one line for each, rather than repeating the engine's raw list of element errors. Read it first: it is the engine talking. A request that never arrived says Could not reach the engine at <url>.
| No engine address | Neither deployment.url nor the Connection dialog gives one for the profile in force. Press Deploy, then Edit connection… in the popover. |
| 404 on Camunda 8 | Use the address of the REST API. Penstock adds /v2/deployments. An address that ends in /v2 works too. |
| 401 or 403 | The user or the client may not deploy. The editor's message offers Edit connection. In a terminal, penstock deploy says which of deployment.auth in penstock.local.yaml, PENSTOCK_PASSWORD, PENSTOCK_CLIENT_SECRET or PENSTOCK_TOKEN to set. |
| No password sent | deployment.auth.type is basic and PENSTOCK_PASSWORD is not set. penstock deploy and penstock doctor say so before anything is sent. A password: key in penstock.local.yaml is not read. |
| OAuth | A failed token request is reported apart: the endpoint could not be reached, answered with an error, or sent no access_token. |
| "The preDeploy hook failed, nothing was sent" | Read the hook's output that follows. In an untrusted project a configured preDeploy is not run, and the deployment stops. |
| Certificate errors | Penstock has no option to skip certificate checks. Trust the certificate in the runtime of your tool. |
| Timeouts | 10 seconds to connect, 30 seconds for the request, 15 for the token. |
| Wrong password saved | Open Edit connection… from the Deploy popover, type the right one, Save and Deploy. Set Sign in to Not needed and save to forget it. |
See Deployment.
Element templates do not appear
Templates come from .camunda/element-templates folders next to the diagram or above it, and from elementTemplates in penstock.yaml. The Classic BPMN editor ignores them, so check the engine first. A listed path that does not exist adds nothing and says nothing in the editor. penstock doctor reports it as missing. A file over 10 MB is skipped, and a file that is not valid JSON is skipped with a line in the log of your tool. See Element templates.
The connector browser is empty or cannot download
- Press Retry, or Check for updates.
- It needs to reach
api.github.comandcodeload.github.com, through the proxy settings of your tool. See Security and privacy. - If it worked before, Penstock uses what it downloaded and says Could not check for a newer release.
- From a terminal:
penstock connectors --refresh.
The diagram was changed on disk
The editor asks whether to reload or to keep editing. See The BPMN editor.
A paid feature asks me to buy Pro
Your trial may have ended, or the licence was released or ended. Run penstock license: it says which licence the machine has and where it came from, and during the trial it says the trial is on and until when. A machine in a pipeline needs Team, and a pipeline gets no trial. See Buying and signing in.
The licence is a signed token, checked offline and renewed once a day when the machine is online; offline it keeps working until it runs out, and the message says how many days are left. A machine whose clock has been set back below a time it has already seen is refused, with the reason given.
Test cases will not run
- is not marked deployment.forTests: mark the profile, or confirm once when your tool asks.
- A case is not run because it lacks what the Camunda test-case schema requires: an assertion with no
processInstanceSelector, or an instruction with a property the schema does not allow. The message says which. - A step waits and fails: no worker took it in time. Start the worker or mock the step.
See Scenarios.
Where else to look
- The log and the developer tools of your tool. See the troubleshooting page of your tool.
- The list of files Penstock reads and writes.
- The questions and answers.
Still stuck
Open an issue on the support tracker. Add the tool and its version, the version of Penstock, the engine, the output of the doctor, and a .bpmn file that shows the problem. Security problems go to SECURITY.md, not to a public issue.