Skip to main content

Troubleshooting and Limitations

Find which layer fails first, then apply the matching section below.

Triage Order

  1. Reproduce with the smallest input: one batch, a few rows, default configuration.

  2. Run ayx_plugin_cli test. A failure here is a back-end, test data, or import problem.

  3. If tests pass, build with create-yxi. A failure here is a packaging problem.

  4. 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

ayx_workspace.json not found

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 --omit-ui.

Tool <name> not found in workspace. (from update-tool-help).

The name must match a key under tools in ayx_workspace.json exactly.

"No tools in workspace. Add tools before packaging."

Run create-ayx-plugin before create-yxi or designer-install.

A prompt appears unexpectedly in an unattended run.

Pass every option as a flag, and answer the optional namespace prompt of create-ayx-plugin with an empty line.

create-ayx-plugin failed partway.

Clean up the leftover files. For more information, go to the Command Reference

ayx_plugin_cli is not recognized.

The CLI is not installed in the active environment. For more information, go to Set Up Environment.

Failing Tests

Check in this order:

  1. The plugin logic produces wrong values. Print or assert intermediate results.

  2. 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.

  3. The test can't import the back end. Run pytest from 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.

KeyError on the output anchor.

Same as above. For multiple-output plugins, check Output1 and Output2.

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_UNSUPPORTED needs --openssl-legacy-provider in the panel’s build scripts, or an older Node.

  • If create-yxi seems to hang after the panel build, look for build/yxi/<package>.yxi before 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:

  1. Python version. backend_language_settings.python_version must match the Designer release’s embedded Python. Symptoms are import errors and syntax or standard library differences. Regenerate config files after changing it.

  2. Dependencies. Every third-party import must be in backend/requirements-thirdparty.txt. A --dev install uses the CLI’s own environment instead of bundling, so if imports fail after designer-install --dev, run a normal designer-install.

  3. 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\Tools for user, %ALLUSERSPROFILE%\Alteryx\Tools for admin).

  4. Configuration keys. The names the panel writes must be the names the backend reads.

  5. 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

  1. Restart Designer.

  2. Confirm the install location matches the install type you used.

  3. Search by plugin name and search tags, and check the tool category in ayx_workspace.json.

  4. Confirm generate-config-files ran 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.

  1. A hand-written panel is not sending the SetConfiguration acknowledgment at the end of its save handler, so Designer discards the session’s edits without an error.

  2. The panel writes a key outside the persisted configuration model.

  3. The default configuration is missing the key, so it starts undefined.

  4. 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-yxi does 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.json or 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_version from ayx_workspace.json

  • The exact command and its full output.

  • The smallest workspace that reproduces the problem.

Remove credentials from logs and configuration first.