Troubleshooting Extensions for Local Development

Use this guide when an extension doesn’t show up in your local Meshery development environment. Meshery extensions integrate in two different ways, and each fails differently, so first find out which kind you have.

Step 1: Find the extension’s repository

Most Meshery extensions are open source, with repositories in the meshery-extensions GitHub organization. Find the repository for the extension you are troubleshooting.

If the repository is public, follow the steps for Loosely-Coupled Extensions.

If you can’t find it, or it is private, the extension is probably tightly coupled, and the problem is probably a dependency mismatch. Follow the steps for Tightly-Coupled Extensions.

Step 2: Troubleshoot by extension type

Loosely-Coupled Extensions

These extensions run as separate processes and talk to Meshery Server through its APIs, so you can inspect them directly.

• Example: Meshery Adapters like the meshery-istio adapter.
• Common issues: networking problems, port conflicts, or errors in the extension itself.
• Debugging steps: run docker ps to check that the container is running, and docker logs <container-id> to read its logs. If Meshery runs in Kubernetes, use kubectl get pods -n meshery and kubectl logs.

Tightly-Coupled Extensions

These extensions load into Meshery UI as plugins, so they need package versions that exactly match your Meshery build.

• Example: Kanvas, the collaborative visual designer.

Why you can’t fix this locally

The extension’s source repository is private, so:

• You can’t build the extension from source.
• You can only use a pre-built package.

The dependency mismatch problem

A pre-built package works only if its dependencies happen to match your local Meshery build:

• Updating your local Meshery can break a package that worked before.
• Failures often show no clear error message.
• Without source access, you can’t rebuild the package to match.

Next steps

You can try other package versions from the meshery-extensions-packages repository, but trial and error isn’t guaranteed to work. Instead:

• Ask for help in the Meshery community.
• Check access requirements or find maintainers in the community handbook.