Troubleshooting and Limitations
Find which layer fails first, then apply the matching section below.
Triage Order
Reproduce with the smallest input: one batch, a few rows, default configuration.
Run
ayx_plugin_cli test. A failure here is a back-end, test data, or import problem.If tests pass, build with
create-yxi. A failure here is a packaging problem.If the package builds and the plugin misbehaves in Designer, compare Designer against your local environment (go to Works Locally, Fails in Designer).
CLI errors appear in the terminal as ERROR: <message>, with a description of the cause, and the command exits with code 1.
CLI Errors
Message or Symptom | Action |
|---|---|
| Run the command from the workspace root. |
Duplicate plugin name, or "may already exist in workspace". | Class and file names must be unique across the workspace. Choose another name. |
Plugin name error. | Use a name that starts with a letter and has only letters, digits, and spaces. |
Node or npm version error. | Install Node 18 or later, or use |
| The name must match a key under |
"No tools in workspace. Add tools before packaging." | Run |
A prompt appears unexpectedly in an unattended run. | Pass every option as a flag, and answer the optional namespace prompt of |
| Clean up the leftover files. For more information, go to the Command Reference |
| The CLI is not installed in the active environment. For more information, go to Set Up Environment. |
Failing Tests
Check in this order:
The plugin logic produces wrong values. Print or assert intermediate results.
The test data is wrong: input rows, expected rows, schemas, or the configuration mock do not match the scenario. Anchor names in the test must match the plugin’s anchors.
The test can't import the back end. Run
pytestfrom the workspace root.
Symptom | Likely cause |
|---|---|
Output data is empty. | The plugin wrote to an anchor name that does not exist, wrote in the wrong callback, or never ran the callback the test drives. |
| Same as above. For multiple-output plugins, check |
Generated test expects no log messages and now fails. | The plugin now logs. Update the assertion. |
Expected and actual rows differ in column order or type. | Arrow schema mismatch, often from a pandas round trip changing integer or string types. |
A test passes alone and fails with others. | Shared mutable state in the plugin class or the test data. |
Packaging Failures
For more information, go to Package and Install. In short:
A panel build that fails with
ERR_OSSL_EVP_UNSUPPORTEDneeds--openssl-legacy-providerin the panel’s build scripts, or an older Node.If
create-yxiseems to hang after the panel build, look forbuild/yxi/<package>.yxibefore running it again.If the build fails in the panel step, read the panel build log first. Don't assume the backend is at fault.
Works Locally, Fails in Designer
Compare in this order:
Python version.
backend_language_settings.python_versionmust match the Designer release’s embedded Python. Symptoms are import errors and syntax or standard library differences. Regenerate config files after changing it.Dependencies. Every third-party import must be in
backend/requirements-thirdparty.txt. A--devinstall uses the CLI’s own environment instead of bundling, so if imports fail afterdesigner-install --dev, run a normaldesigner-install.Stale install. Restart Designer after the first install and after any metadata change. Confirm the plugin folder exists in the Tools directory for the install type you used (
%APPDATA%\Alteryx\Toolsfor user,%ALLUSERSPROFILE%\Alteryx\Toolsfor admin).Configuration keys. The names the panel writes must be the names the backend reads.
Environment. Proxy settings, file paths, locale, and permissions differ between your machine and the workflow’s environment.
Plugin Does Not Appear in the Tool Palette
Restart Designer.
Confirm the install location matches the install type you used.
Search by plugin name and search tags, and check the tool category in
ayx_workspace.json.Confirm
generate-config-filesran after the last metadata change and the package was rebuilt.
Settings Are Not Saved
A setting looks right while the panel is open but is blank or default after you save and reopen.
A hand-written panel is not sending the
SetConfigurationacknowledgment at the end of its save handler, so Designer discards the session’s edits without an error.The panel writes a key outside the persisted configuration model.
The default configuration is missing the key, so it starts undefined.
The back end reads a different key than the panel writes, so a saved value looks lost.
Known Limitations
Plugin names must start with a letter and contain only letters, digits, and spaces.
The CLI supports one backend language: Python.
The CLI supports Python 3.10 and 3.13. It does not support Python 3.11, 3.12, or 3.14 and later.
install-yxidoes not support YXIs built with the original, pre-CLI Alteryx Python SDK.If you connect a Python SDK plugin to a Text Input tool with no rows, it triggers an unrelated error. Add rows to the Text Input tool.
Editing
ayx_workspace.jsonor the generated configuration files by hand can cause unpredictable results. Use CLI commands where one exists.
When Asking for Help
Include this information:
The CLI version (
ayx_plugin_cli version) and SDK version.Designer version.
python_versionfromayx_workspace.jsonThe exact command and its full output.
The smallest workspace that reproduces the problem.
Remove credentials from logs and configuration first.