Troubleshoot#

This guide takes you from a symptom to its cause and its fix. Each entry says which interfaces it applies to. The examples use the Compose site; see Run a Plone site for testing.

export PLONE_CLIENT_PASSWORD=admin

The site cannot be reached#

Applies to the library, the command line, and the MCP server.

plone-client --url http://localhost:9 -u admin info
{
  "error": {
    "type": "PloneConnectionError",
    "message": "GET http://localhost:9/++api++/@actions?categories%3Alist=user: [Errno 61] Connection refused"
  }
}

The address is wrong, or the site is down. The exception is PloneConnectionError, and the exit code is 8. Open the URL in a browser, and check the port and the site id. A backend without a frontend has the site id in its URL, as in http://localhost:8080/Plone.

The site answers as if you had not logged in#

Applies to the library, the command line, and the MCP server.

Plone answers a wrong password as an anonymous request, so reads of public content still work, and only changes fail.

PLONE_CLIENT_PASSWORD=wrong plone-client --url http://localhost:8080/Plone -u admin info -f authenticated,credentials_rejected
{
  "authenticated": false,
  "credentials_rejected": true
}

credentials_rejected says that the site refused the secret, and info exits with code 4. Fix it with plone-client profile set-secret NAME, and see Manage profiles.

Lists and items come back empty#

Applies to the library, the command line, and the MCP server.

An address that ends in ++api++ is not an error: the requests work, and their answers are empty.

plone-client --url http://localhost:8080/Plone/++api++ -u admin get /news -c
{"context": "http://localhost:8080/Plone", "message": "http://localhost:8080/Plone/++api++/news", "type": "Redirect"}

Give plone-client the address of the site, because it adds that segment by itself. The address of a Compose site is http://localhost:8080/Plone.

Requests end in a server error about portal_catalog#

Applies to the library, the command line, and the MCP server.

The address has no site id, so the request reaches the server and not the site.

plone-client --url http://localhost:8080 -u admin ls /
{
  "error": {
    "status_code": 500,
    "type": "AttributeError",
    "message": "portal_catalog",
    "method": "GET",
    "url": "http://localhost:8080/++api++/@search?path.depth=1&sort_on=getObjPositionInParent&b_size=100"
  }
}

Add the id of the site to the address, as in http://localhost:8080/Plone.

A change is refused with 401 or 403#

Applies to the library, the command line, and the MCP server.

Exit code 4 covers two causes: the user lacks the permission, or someone holds a lock on the item. A missing permission answers 401, even to a user who is logged in.

PLONE_CLIENT_PASSWORD=correct-horse-battery plone-client --url http://localhost:8080/Plone -u jdoe registry set plone.site_title '"New title"'
{
  "error": {
    "status_code": 401,
    "type": "Unauthorized",
    "message": "You are not authorized to access this resource.",
    "method": "PATCH",
    "url": "http://localhost:8080/Plone/++api++/@registry"
  }
}

Give the user a role that has the permission, or use another user; see Manage users and sharing. A lock answers 403.

plone-client --url http://localhost:8080/Plone -u admin request POST /about/@lock -d '{}' -f locked,creator
{
  "locked": true,
  "creator": "admin"
}
PLONE_CLIENT_PASSWORD=correct-horse-battery plone-client --url http://localhost:8080/Plone -u jdoe update /about --title "New title"
{
  "error": {
    "status_code": 403,
    "type": "Forbidden",
    "message": "Resource is locked.",
    "method": "PATCH",
    "url": "http://localhost:8080/Plone/++api++/about"
  }
}

Read lock in plone-client get /about -f lock to see who holds it. A lock ends by itself after its timeout, or when its owner removes it.

plone-client --url http://localhost:8080/Plone -u admin request DELETE /about/@lock -f locked
{
  "locked": false
}

A type is refused with Disallowed subobject type#

Applies to the library, the command line, and the MCP server.

The site does not allow that type in that place. On a Volto site, this usually means Folder, which exists but cannot be added.

plone-client --url http://localhost:8080/Plone -u admin create / Folder --title Archive
{
  "error": {
    "status_code": 403,
    "type": "Forbidden",
    "message": "Disallowed subobject type: Folder",
    "method": "POST",
    "url": "http://localhost:8080/Plone/++api++"
  }
}

To make a section, such as /news, create a Document (a Page), which is folderish.

plone-client --url http://localhost:8080/Plone -u admin create / Document --title Archive -f @type,id
{
  "@type": "Document",
  "id": "archive"
}

A dry run warns about this, in warning, and exits with code 0.

plone-client --url http://localhost:8080/Plone -u admin -n create / Folder --title Archive -f dry_run,warning
{
  "dry_run": true,
  "warning": "The site would refuse this: Folder cannot be added in /. It can add: Event, File, Image, Link, News Item, Document. The site would ignore fields that Folder does not have: blocks, blocks_layout."
}

To check first, list what a folder can hold.

plone-client --url http://localhost:8080/Plone -u admin types --addable-in /archive
[
  "Event",
  "File",
  "Image",
  "Link",
  "News Item",
  "Document"
]

Assistants use the content_types tool, with addable_in, for the same list.

A field does not change, and there is no error#

Applies to the library, the command line, and the MCP server.

Plone ignores the fields that a content type does not have, so a misspelled field gets no error and no effect.

plone-client --url http://localhost:8080/Plone -u admin update /about -s titel=Oops -f title
{
  "title": "About"
}

List the fields of the type before you set them.

plone-client --url http://localhost:8080/Plone -u admin types Document -f title,required
{
  "title": "Page",
  "required": [
    "title"
  ]
}

A transition is refused#

Applies to the library, the command line, and the MCP server.

Each workflow state has its own transitions: a published item cannot be submitted.

plone-client --url http://localhost:8080/Plone -u admin workflow /about submit
{
  "error": {
    "status_code": 400,
    "type": "WorkflowException",
    "message": "No workflow provides the '${action_id}' action.",
    "method": "POST",
    "url": "http://localhost:8080/Plone/++api++/about/@workflow/submit"
  }
}

The message is the raw one of Plone, with its unfilled ${action_id}. Ask which transitions the item has now.

plone-client --url http://localhost:8080/Plone -u admin workflow /about -f state,transitions
{
  "state": {
    "id": "published",
    "title": "Published"
  },
  "transitions": [
    "reject",
    "retract"
  ]
}

The block types come from builtin#

Applies to the library, the command line, and the MCP server.

The answer describes only the core blocks when plone-client could not ask Volto.

plone-client --url http://localhost:8080/Plone -u admin block-types -f source,warning
{
  "source": "builtin",
  "warning": "http://localhost:8080/Plone has no @blocks-schema service; set frontend_url to the Volto server, or upgrade Volto"
}

Set the frontend_url of the site, and use Volto 19.6.0 or later.

PLONE_CLIENT_FRONTEND_URL=http://localhost:3000 PLONE_CLIENT_URL=http://localhost:8080/Plone PLONE_CLIENT_USERNAME=admin plone-client block-types -f source
{
  "source": "site"
}

When the warning says that @blocks-schema needs an authenticated user, the site has the service, and the profile reads it anonymously. Use a profile that logs in.

A certificate is refused#

Applies to the library, the command line, and the MCP server.

A site with a self-signed certificate, or one from a private authority, fails with a connection error. Set verify to the path of the certificate of the authority; see Configuration.

Markdown pages fail with exit code 3#

Applies to the library, the command line, and the MCP server.

create-page and upload-tree --pages need the markdown extra, which needs Python 3.12 or later. On Python 3.11 the extra installs nothing, so the error remains. Install the extra as Install plone-client shows, on Python 3.12 or later.

The keyring is not available#

Applies to the command line and the MCP server.

A container or a CI job often has no keyring, and profile add ends with this error, and exit code 1.

keyring.errors.NoKeyringError: No recommended backend was available.

Keep the secret in an environment variable; see Use the command line in scripts and CI.

A request ends in 409#

Applies to the library, the command line, and the MCP server.

The request conflicts with the state of the site, such as a change that someone else saved first. The exception is PloneConflictError, and the exit code is 6. Read the item again, and repeat the change.

Requests get slow, or end in 429#

Applies to the library, the command line, and the MCP server.

The client repeats idempotent requests after 429, 502, 503, and 504, and waits as long as Retry-After says. A POST is never repeated, so it fails on the first of these answers. Lower your rate, or set retries and backoff; see Configuration.

The MCP server does not start#

Applies to the MCP server.

Exit code 3 means that the mcp extra is missing, or that the profile is unknown; the error says which. Install the extra as Install plone-client shows, and run the command that your MCP client runs, in a terminal, to read the error.

An MCP client does not show a tool#

Applies to the MCP server.

--tool offers only the tools you name, and a server of a read-only site does not offer the tools that change it. MCP server says which tools each mode offers.

An HTTP client gets 401 or 421#

Applies to the MCP server over HTTP.

401 means that the bearer token is missing or wrong, and 421 means that the Host header is not one the server accepts. Connect an assistant through the MCP server shows how to set both.

The demo site shows something else#

Applies to everything that uses demo.plone.org.

The demo site is shared with other visitors, and resets every night, so its content does not always match these pages. Use your own Compose site for anything that must stay the same; see Run a Plone site for testing.

A tutorial failed half way#

Applies to every tutorial.

A step that fails leaves the Compose site and your profiles in between two states, and the next steps may no longer match the page. Reset the site with docker compose down -v, remove each profile the tutorial created with plone-client profile remove NAME, and start the tutorial again from its first section.