Troubleshooting

Most errors appear as a short message at the top of the window. Messages that end in (code: N) come from the PDK server. The code is the PDK’s own status code, not a gRPC status code:

Code	Name	Meaning
1	NOT_FOUND	The named item was not found.
2	INVALID_ARGUMENT	The request had invalid arguments.
3	INTERNAL_ERROR	The request failed on the server, for example no IK solution.
4	FAILED_PRECONDITION	A precondition is not met, for example no active workcell.
5	PERMISSION_DENIED	The feature needs a license this computer does not have.

The terminal running run_app.sh shows more detail.

The browser shows a blank page or {"detail":"Not Found"}

The editor was not built. Run npm install in app/frontend and start again with ./run_app.sh. Check the terminal for build errors.

npm run build fails with a syntax or engine error

Node.js is too old. Install Node.js 20.19+ or 22.12+ (Install Composer Studio).

flexiv.pdk is not available

The backend runs in a Python environment without flexivpdk. Activate the virtual environment you installed into, or install flexivpdk into it (Install Composer Studio).

Failed to fetch workcells., or other requests fail with no detail

The backend cannot reach the PDK server. Check that the server is running, and that NEBULA_TARGET names it (default localhost:50052). Test with pdk-scene workcell list.

The path "<path>" does not exist. Please specify a valid Nebula release folder to continue.

The PDK Release Folder is wrong. Choose the folder that holds the server’s workcell/ directory (Launch Composer Studio).

... (code: 4): No active Workcell is loaded

No workcell is active on the server, for example after the server restarted. Load a workcell with Workcell Setup (Workcells).

... (code: 5)

The feature needs a license this server does not have. Open the License Manager (Activate Licenses).

Requests fail with a gRPC INTERNAL error and no details

The flexivpdk version does not match the server. Install the version matching your server release (Install Composer Studio).

A mesh, robot or area does not appear after loading a workcell

Composer Studio reads these files from the PDK Release Folder. Check that the folder is correct, and that WORKCELL_ROOT and NEBULA_ROOT map the same folder as seen by Composer Studio and by the server (Launch Composer Studio).

Insert stays disabled for a mesh

Select an .obj file and enter a Name. Only .obj meshes are supported. If a Required .mtl file row is shown, select that file too.

The + buttons in the tree are disabled

Load a workcell first, and make sure Live Scene Events is off. The buttons are also disabled while a Setup Area or Setup Path form is open; close it first.

Nothing happens when I double-click the object

Double-clicking places points only while the Setup Area or Setup Path form is open, and only on that form’s object.

Create Trajectory stays disabled for a linear path trajectory

The robot cannot reach the first pose of the path. Adjust the Initial Configuration, the Normal Offset, or the position of the part or robot (Linear Path Trajectories).

Collision check failed: IK computation failed: IK solver failed due to collision (code: 3)

The pose collides with the scene or with the robot itself, given the default collision configuration. Change the pose, or adjust the margin and excluded pairs (Collision Configurations).

PTP planning fails

Check that every target is collision-free and that the Collision Margin is not larger than the free space around the robot. Planning always uses the default collision configuration.

Failed to connect to system:

See the table in Connect to a Real Robot.

The robot does not move when I use the Position tab

This is expected: jogging the real robot is not available in this release (Connect to a Real Robot).

Composer Studio changes made in another window do not appear

Composer Studio does not refresh on its own. Load the workcell again, or turn on Live Scene Events to follow scene-object changes (Live Scene Events).

Port 8011 is already in use

Another Composer Studio is running. Stop it, or start the backend on another port (Launch Composer Studio).