Troubleshooting

Find the symptom, read the likely cause, and do what the third column says. Limitations and known issues holds the limits behind many of these symptoms, and Glossary defines the terms. Installation problems are also covered in Installation troubleshooting.

Before you start

Look at EA's screen. A dialog open inside EA is the most common cause of a call that hangs, and it holds every later call until someone dismisses it. A dialog is not a defect in AI Power Tools. With computer use, the assistant sees the dialog in EA's window, reads it, uses the message to correct the call, dismisses the dialog and keeps going. Without computer use, you take a screenshot of the dialog and paste it into the conversation so the assistant can analyze it, then you dismiss the dialog so processing can continue.
Run ping, then get_repository_info. ping proves the server is alive and gives its version. get_repository_info proves EA is reachable and shows which project is open. See Verifying an installation.
Do not retry blindly. Confirm the previous call failed before you issue it again, and never start a second EA to bring one forward.

Installation and loading

Symptom	Likely cause	What to do
Every skill appears twice, one set prefixed `ai-power-tools:`	The plugin and an older installer's copy in your user skills folder are both loaded, and nothing deduplicates them	Run `migrate-to-plugin.ps1` with its preview option first, then for real. It finds copies from the oldest installer versions too. If it reports nothing to migrate but the duplicates remain, run `prune_legacy_skills` as a dry run to see what the server recognizes. See Moving from an older installation
The assistant says the legacy installer declined because the plugin already supplies the skills	This is deliberate, to avoid loading every skill twice	Update the skills through the marketplace sync instead. Force a second copy only if you want one
The plugin is installed but the skills do not appear	Claude Desktop has not been restarted since the plugin was installed or synced	Quit Claude Desktop completely and reopen it. In Claude Desktop, confirm the plugin is enabled
The skills are there but no EA tools appear, or `ping` is not found	The Claude Desktop extension that supplies the server is not installed, or it is turned off. The plugin carries only the skills	Install the extension: download `AI-Power-Tools-for-Sparx-EA.mcpb`, drag it onto Settings > Extensions in Claude Desktop, click Install and keep it enabled. See Claude Desktop extension
The EA tools work in the Code tab but not in Claude Code in a terminal	Claude Code in a terminal does not load Claude Desktop extensions, so it has no server	Use the Code tab of the Claude desktop app. See Supported clients
Skills are missing in Claude Desktop chat or Claude Cowork but work in Claude Code	Those surfaces read skills from plugins only, not from the user skills folder	Install the plugin on your Claude account from the `novocircle` marketplace, then quit Claude Desktop completely and reopen it. See Supported clients
Adding the marketplace fails or is refused	Organization policy blocks third-party marketplaces, or the network blocks GitHub	Use managed settings if policy allows, or your organization's own provisioning. See Enterprise fleet deployment
The skills are out of date	The claude.ai marketplace does not sync on its own, and an uploaded plugin file never updates itself	Open https://claude.ai/customize/plugins, choose Manage marketplaces and sync `novocircle`, then quit Claude Desktop completely and reopen it. For an uploaded plugin file, upload the newer file from the skills release
Skills are present but `ping` fails	The server did not start: the Claude Desktop extension is off, or Claude Desktop dropped it	Open Settings > Extensions in Claude Desktop, confirm the extension is installed and enabled, and restart Claude Desktop
A plugin details command shows no MCP servers	The plugin carries only the skills. The server comes from the extension	Ignore it and test with `ping`
The skills load twice in the Code tab	The plugin is installed on the claude.ai account and also through Claude Code's own plugin commands	Keep the account install and remove the copy installed through Claude Code's plugin commands
A Claude Cowork session has the skills but no EA tools	It is a cloud session, which has no local MCP server; or Claude Desktop is not running on the workstation, the extension is not installed or is off, or a repackaged manifest has a required setting with no default and the desktop dropped the server	For modeling and analysis, start a local session. Run Claude Desktop with the extension enabled and EA on the same workstation, and use the shipped manifest unmodified
An extension upgrade fails with a file-lock error naming the server program	The running server holds a lock on its program file	Disable the extension in the install preview, or quit Claude Desktop from the system tray, then install
Windows blocks the server, or SmartScreen shows "Unknown publisher"	A build older than the signed releases, a modified package or an unsigned local build. Release builds are signed	Install the current release asset from the public releases repository. Do not add Defender exclusions
The server reports an update	The update check found a newer release. The notice gives the upgrade steps for how the server was installed: the Claude Desktop extension, the VS Code extension, or a location it does not recognize	Follow the steps in the notice. For the extension, switch its Enabled toggle off, click Update, then switch it back on. See Updating and uninstalling
`ping` returns a notice that your skills are behind the current release	The skills on your Claude account are older than the current release	Show it as written and follow it: sync `novocircle` under Manage marketplaces, then quit Claude Desktop completely and reopen it
The skills check lists skill copies in your user skills folder	An older installer left copies there, and they load a second time beside the plugin's skills. When the plugin is found installed the check reports only such leftovers; when the plugin is only reported by the session, the note says the copies duplicate the plugin's skills if you installed it on your account	Run `migrate-to-plugin.ps1`, with its preview option first. Or tell the assistant you installed the plugin on your claude.ai account and ask it to remove the copies with `prune_legacy_skills`. See Moving from an older installation
A skill calls an operation that "does not exist"	The server is older than the skill expects, because the skills and the server update separately	Compare the version from `ping` with the skill's minimum server version, and update the older one. See How skills work
VS Code: "requires VS Code 1.99 or newer"	VS Code is too old for native MCP support	Update VS Code
VS Code: "only runs on Windows"	A non-Windows platform	Not supported. EA is Windows-only
VS Code: "Could not find ea-mcp-server.exe"	The server path setting points at a missing file, or the extension is damaged	Clear the setting or reinstall the extension. See VS Code extension
VS Code has the tools but no skills	The `ai-power-tools` plugin is not installed in VS Code. VS Code does not read the plugin installed for Claude	Run EA: Set Up Skills, then choose Install on `ai-power-tools` in the Agent Plugins view. See VS Code extension
VS Code: the update notice does not appear	The daily check ran recently, the version was skipped, or the update-check setting is off	Run EA: Check for Updates
A change to a server setting has no effect	The server reads its environment once, at start	Restart the server. In VS Code, run EA: Restart MCP Server

Connection to Enterprise Architect

Symptom	Likely cause	What to do
The assistant reports that EA is not running	There is no EA instance to attach to. The server never starts EA by itself	With computer use, the assistant can start EA and open the model: say so, and it asks first. Check that EA is not already running before you agree. Without computer use, start EA yourself and open a project
The assistant reports that no model is open	EA is running with no project open	Open a project in EA, or ask for `open_model` (an existing file). `create_model` makes a new one
The assistant is working in the wrong model	More than one project is or was open, or the server attached to an EA instance you did not expect	Ask for `get_repository_info` and read the connection and project path. `open_project` opens only if the path differs; `open_model` always issues an open. Close other EA windows
Results look empty or belong to another model	Ids belong to one repository and are not stable across models	Look the items up again in the model you intend, with `find_elements_by_name` or `list_root_packages`
A message mentions an "Operation unavailable" error (code 0x800401E3)	EA is not responding, usually because a dialog is open	Deal with the dialog: with computer use the assistant reads it, corrects the call and dismisses it; without computer use you screenshot it into the conversation, then dismiss it. Save, then retry. If it persists, restart EA
EA shows "(Not Responding)"	EA is busy opening a model, importing a technology or file, or running a large operation	Wait and check again. Do not re-issue the command, double-click, or open a second instance
A call never returns	A dialog inside EA, often from SQL its backend cannot run, a malformed merge document or an import with GUIDs preserved	With computer use the assistant reads the dialog in EA's window, corrects the call from its message and dismisses it. Without computer use, screenshot the dialog and paste it into the conversation so the assistant can analyze it, then dismiss it. Fix the cause, then re-run
A call never returns after an XMI import	The import ran with GUID stripping off into a model that already holds those GUIDs	Leave GUID stripping on. Wait, then check EA for a dialog
`generate_report` hangs	An empty template name was passed	Never pass an empty template. Handle any dialog as described in Before you start, and use a template that exists
"Request timed out" or "Connection closed" on a wide scan	Several sessions are using the repository, or the scan covers the whole model	Retry once. Scope the scan to the smallest package that answers the question. Check EA for a dialog before concluding anything
Opening or creating a model fails	EA refused the file. `create_model` has been reported to fail on EA build 1716	Check the path and the file. Create the model in EA and open it with `open_model`
`launch_ea` fails	EA did not become responsive within 30 seconds	Start EA manually, or let the assistant start it through the desktop if computer use is available
EA is open twice	A second instance was started to bring the first forward, or `launch_ea` was used while EA ran	Close the extra instance. Never open a second EA against the same file. To bring EA forward, click its taskbar button
EA will not open because the seat is in use	A per-user Sparx license limits concurrency to one instance	Close the other session
Calls fail after EA restarts or the project reopens	The server held a stale connection	The server reconnects on the next call. A COM script you wrote must attach again
A write by query succeeded but EA still shows the old state	A direct query changed the database underneath EA's session	Reload: `reload_diagram` for a diagram, or reload the package in EA

Capabilities and surfaces

These symptoms come from what your surface can do, not from a defect. See Capabilities and surfaces for which surfaces have which capability, and Limitations that depend on your surface's capabilities for the limits.

Symptom	Likely cause	What to do
The assistant asks you to perform a UI step, or asks what you see on screen	No computer use on this surface, so the assistant cannot operate or see EA's window or Power BI Desktop	Do the step, then tell the assistant what happened or paste what you see. Or switch to a surface that has computer use
An engine-based skill reports that it cannot run	The surface has no local code execution, or Python 3 or a needed package is missing on the machine where EA runs: `pywin32` (scripts the AI writes against EA, as in `ea-com`), `pyyaml` (composition notation bindings) or `pyarrow` (Parquet files, not bundled)	Ask which of these it is. Install the missing package for the Python the engines use, or use a surface with local code execution. Server operations work either way
A reporting skill cannot make the inclusion choice, run the governance gate, write Parquet files or generate a Power BI project	The surface has no local code execution, or Python 3 is missing on the machine where EA runs. These steps are code engines and have no fallback	Use a surface with local code execution. The AI Power Tools MCP Server for Sparx EA still builds, checks, replays and refreshes the business layer from a reporting profile that already exists
A Prolaborate skill cannot proceed	The surface has no browser control, or there is no signed-in Prolaborate session	Use a surface with browser control (a built-in browser or Chrome), and sign in to Prolaborate yourself. Computer use cannot replace browser control. See Prolaborate below
The assistant reports that EA is not running	There is no EA instance to attach to. The server never starts EA by itself	With computer use, the assistant can start EA and open the model, and it asks first. Without it, you start EA and open a project

Requests the assistant rejects or reports as failed

Where a request fails, the assistant normally reports a short message. These are the ones you see most, in plain words, with the code name in parentheses where the transcript shows one. They are grouped by what went wrong. Whatever the wording, a response that carries an error or a failure flag has failed, even if it also says other things.

The request is malformed

What the assistant reports	Meaning	What to do
The operation name contains arguments (`invalid_operation_format`)	Arguments were put in the operation name	Use the bare operation name and put every argument in the parameters
The tool has no such operation	A mistyped operation name, or one the tool recognizes but does not provide	Choose a name from the list the response gives, or from How tools and operations work
A parameter is not recognized (`unknown_parameters`)	The call includes a key the operation does not declare. A parameter placed outside the parameters block is never read	Read the "did you mean" suggestion and the accepted list, then rename or remove the key
A required parameter is missing (`missing_required_params`)	The unknown-key check runs first, so a typo is reported as "unknown", not "missing"	Add the named parameters
A value is not allowed (`invalid_direction`, `invalid_mode`, `invalid_scope`, `invalid_layout_style` and similar)	A setting has a fixed list of values, matched exactly	Use a value from the list the response returns, or omit the setting to take the default
Read-only mode is on (`readonly_mode`)	Read-only mode is switched on and the operation modifies the repository, including a diagram layout change	In Claude Desktop, switch off Read-only mode on the extension's Configure screen if writes are intended. Where another client launches the server, remove `EA_MCP_READONLY` from the server's environment. Then restart the server
The operation is not available (`not_yet_implemented`)	One of the `ea_validate` names other than `audit` was called	Use `audit`

The thing you named was not found

What the assistant reports	Meaning	What to do
A package, element, connector or diagram was not found (`package_not_found`, `element_not_found`, `connector_not_found`, `diagram_not_found`)	The id or GUID does not exist in this repository. Ids differ between models	Find the real id with `find_packages_by_name`, `find_elements_by_name`, `list_connectors_for_element` or `find_diagrams_by_name`
A connector's source or target was not found (`source_not_found`, `target_not_found`)	An endpoint id does not exist	Check the element ids
An element is not placed on this diagram (`element_not_on_diagram`)	The operation needs the element on the diagram first	Place it with `add_elements_to_diagram_bulk`
No stored link for that connector (`link_not_found`, `link_not_stored`)	EA draws the connector but no stored link exists, or the connector is not on the diagram	Add it with `add_connectors_to_diagram_bulk`, then retry
A file was not found (an XMI file, an image file, a ruleset path)	The path is wrong. A ruleset argument that contains a slash is read as a path unless it also contains a newline	Fix the path. The response gives the resolved path for a ruleset
An unknown table (`unknown_table`)	A mistyped EA table name	Use `list_ea_tables`

EA refused a write

When EA's own save refuses a change, the assistant reports a rejection (connector_rejected, update_rejected, diagram_rejected, placement_rejected and similar), usually with a detail line. The most common cause is a connector type that is not valid between those two stereotypes. Read the detail, check the type and stereotypes, and read the object back. Rejections are reported only where the operation checks for them. Other write sites cannot report one, so a write that reports success and changes nothing needs the checks in the next section.

What the assistant reports	Meaning	What to do
A style or image write was not confirmed, or the placement could not be read back	The write ran but could not be confirmed on a re-read	Check with `verify_diagram`
The placement has no style identifier (`placement_has_no_duid`)	Custom Style needs a placement EA created itself. Placements added through the API have none	Use `set_diagram_object_appearance` for fill, border, font, size and z-order. Apply Custom Style once through EA's user interface if you need shape or opacity
Nothing to write, or no lever applied	The request held no accepted change	Check the values and the rejected-property list on the item

Baselines, import, export and reports

What the assistant reports	Meaning	What to do
Creating or comparing a baseline failed (`create_baseline_failed`, `compare_failed`, `compare_unavailable`)	EA could not complete the baseline step	Confirm the package and the baseline GUID with `list_baselines`. Try from EA's user interface
The baseline restore was not applied (`baseline_restore_not_applied`)	EA accepted the merge but the package still differs from the baseline. Nothing changed	Restore from EA: Package Control, Baselines, Restore
An XMI export failed, is not XMI, or is empty (`xmi_export_failed`, `xmi_export_wrong_format`, `xmi_export_empty`)	The export did not produce a usable file	Do not rely on the file as a backup. Read the detail and retry, and take a baseline instead
An XMI import created nothing (`xmi_import_empty`)	The file held nothing importable, or GUID handling went wrong	Check the file has importable content and keep GUID stripping on
A baseline comparison matches nothing and gives no error	The two GUID forms were mixed	Use the braced form for items and the underscored form for compared packages
`create_baseline` returns an old baseline's GUID	A version label was reused	Use a distinct version and confirm with `list_baselines`
`list_baselines` shows an empty date and author	Reported in some EA builds	Query the model's baseline records for authoritative metadata
A report or diagram export failed (`report_failed`, `export_failed`, `render_failed`)	EA could not write or render the output	Use an `.rtf` output path and a template name that exists, check the path, or reload the diagram and retry

SQL

What the assistant reports	Meaning	What to do
A column does not exist (`invalid_column`)	The server caught an invented or reserved-word column before calling EA	Use `describe_table`. Bracket reserved words such as `[Type]`, `[Default]` and `[Value]`. The check can be bypassed
A write was blocked (`write_blocked`)	Writes are turned off for the call, or read-only mode is on	Use a `SELECT`, or allow writes if you intend one
Zero rows when you expected data	EA returned a blank result, which it does for a query that matches nothing and for some that it fails to run, or the SQL dialect differs	Cross-check with a count query. Use the repository's dialect (`LENGTH` on SQLite, not `OCTET_LENGTH`)
The call fails because the query result could not be read	EA returned a result that cannot be read, for example one over EA's 64 MB limit for query results. It is an error and not an empty result	Narrow the query: fewer rows, fewer columns, and no binary columns. Put a `LIMIT` or `TOP` in the SQL
A column reads as empty where you expected NULL, or the reverse	EA writes NULL and empty text identically in a query result	Do not rely on telling them apart. Where the difference matters, supply your own value
The response is very large	Each row is returned twice (parsed, and as raw XML) and there is no default cap	Set a row cap and turn off the XML copy, and put a `LIMIT` or `TOP` in the SQL
The call hangs with "SQL API Open FAILED"	A SQL function the backend lacks, such as `OCTET_LENGTH` on a `.qea`	Handle the dialog as described in Before you start (the assistant with computer use, otherwise you from a screenshot), then use `LENGTH(...)`

Images and icons

What the assistant reports	Meaning	What to do
The repository type is not supported (`unsupported_repository_backend`)	`add_image` and some icon loading need a local file (`.qea` or `.qeax`)	Load the artwork through EA's Image Manager under the same name, then use `list_images` and `set_element_image`, or open a local file
The image is too large or the wrong format (`image_too_large`, `image_format_unrecognized`, `image_format_not_stored_by_ea`)	The file is over 1 MiB or is not PNG, EMF or WMF	Convert to PNG, EMF or WMF and shrink it
More than one image has that name (`ambiguous_image_name`)	Image names are not unique	Name the image by its id
The icon libraries were not found (`icon_libraries_not_found`)	EA's installed icon libraries could not be located	Set `EA_MODEL_PATTERNS` to the folder that holds them, normally `<EA install>\ModelPatterns`, and restart the server
No icon with that id, or the icon could not be read (`icon_not_found`, `icon_unreadable`)	The id is stale, the libraries changed, or the icon is larger than the 1 MB that is read from a library	Run `find_icon` again and use the id it returns. Choose a smaller icon if the size is the reason

Modeling languages

What the assistant reports	Meaning	What to do
The language is unknown (`unknown_language`)	The technology is not loaded or parsed, and is not in the server's built-in tables	Load the technology in EA, or call `parse_mdg_xml` on its file for this session. Use the exact id shown in Manage Technologies
The stereotype is not in the language (`unknown_language_type`)	There is no silent fallback to another stereotype	Choose a stereotype the language defines
The technology's state cannot be determined (`cannot_determine`, `unknown_mdg`, `mdg_loaded_no_definition`)	No definition was found, or the live load check could not complete	Check the id with `list_registered_technologies`, and cross-check in Manage Technologies
A copy stored in the model cannot be read (`model_technology_unreadable`)	The model stores a copy of the technology under this id, and its stored content cannot be decoded	Re-import the technology, or remove the copy in Manage Technologies
The install is shadowed (`installed_shadowed`)	The model holds the same id at Location: Project, and EA answers from that copy, so the copy just installed at Location: Model has no effect	Ask for the Project copy to be replaced. If EA leaves it, reopen the project and repeat, or remove it in Manage Technologies
EA reported the import as done and stored nothing (`import_not_stored`)	The import into the model succeeded in EA's terms and wrote no rows	Install from an MDG Technology package at Location: Model, or use EA's Import to Model
The MDG XML could not be parsed (`parse_failed`)	The XML is malformed, or contains a DOCTYPE or ENTITY declaration, which is refused	Fix the XML
The import failed (`import_failed`)	The XML is invalid, an id exceeds 12 characters, or a base technology is not installed	Check each of those
An MDG id is too long (`id_too_long`)	The id exceeds EA's 12-character limit, which EA otherwise enforces silently	Shorten the id
The profile export failed (`profile_export_failed`)	The package is not a profile package	Check the package. Always supply a version

Validation and the legacy skills installer

What the assistant reports	Meaning	What to do
The ruleset is not valid YAML, or a rule is malformed (`invalid_yaml`, `invalid_rule_shape`, `built_mdg_unreadable`)	The ruleset is not a valid mapping, a rule has the wrong shape, or a rule that points at a built technology file cannot read it	Read the detail and the rule id, and fix the named rule. Save the file as UTF-8
The ruleset path was not found (`rules_path_not_found`)	The argument looked like a path but no file exists there. `~` and `%VAR%` are expanded, and the resolved path is returned	Fix the path. Inline YAML that contains a slash needs a newline to be read as content
The ruleset address was refused (`rules_fetch_refused`)	The address is `http://`, redirects, or the response is over 2 MB. A release-download link normally redirects	Use an `https://` address that does not redirect, such as a raw-content link, or save the file and pass its path
The ruleset could not be fetched (`rules_fetch_failed`)	The reason is deliberately not returned, so the tool cannot probe an internal network	Check the address and the network, and try a local copy. A host that just received a new file may not serve it immediately
The YAML library is missing (`missing_dependency`)	The server build lacks it	Reinstall the server, and report it if it persists
The skills installer reports a failure (`server_too_old`, `fetch_failed`, `invalid_target`)	The server is older than the skills bundle, the download failed, or the target is not valid	Upgrade the server, check connectivity, or use a valid target

An id that does not exist, in a few places

A mistyped attribute GUID, operation GUID or target package on a move can surface EA's own internal error (code 61704) instead of a clear not-found message. The same code is what a damaged EA session looks like, so verify the id first. A call that supplies neither an id nor a GUID fails with a plain tool error ("Must provide element_id or guid") rather than a structured one.

A write succeeded and nothing changed

Symptom	Likely cause	What to do
The call reports success, but a property you set did not change	A property sent with an empty value is skipped with no trace, an unknown property key was dropped, or the write was rejected at a site that does not report rejection	Compare the applied properties with what you sent and read the rejected-property list. For appearance, read it on the appearance operation. Re-read the object
A tagged value you passed as a property never applied	Tagged values do not go through the properties list	Use the tagged-value operations
A bulk create reports created, but tags or stereotypes are missing	Bulk results do not say which tags or connector stereotypes landed	Verify with `get_element_tags` or `get_connectors_for_element_filtered`
`get_element_tags` returns an empty list	An unknown element id is not reported as not found by that operation	Confirm the element with `get_element`
`find_paths` or `trace_connectors` returns nothing	A wrong id, a wrong direction (downstream is the default), a connector type spelled differently (`Realisation`), or a route longer than the depth limit. These calls do not report a bad id	Check the id, direction and type filter before concluding there is no connection. Treat a truncated result as partial
A package name has `&` in it	EA has been reported to HTML-encode special characters in names on some paths	Read the name back and repair it with `update_package`
`add_parameter` wrote nothing	The parameter name already exists on the operation. It is not an upsert	Recreate the operation to change a parameter

Modeling languages

Several states are easy to confuse. A technology can be installed (its file is registered), embedded (stored in the model, at Location: Project or at Location: Model), registered (known to EA's lists), loaded (live in this EA session) and enabled or not (EA reports a technology disabled in Manage Technologies as loaded). The reliable check for "does it work now" is get_mdg_from_runtime, which reports whether the technology is loaded and enabled, and where it is stored. See Glossary.

Symptom	Likely cause	What to do
Installed but not loaded: `install_mdg` reported success, or an import call returned true, but nothing changed	Success is not proof. EA caches technologies, and an application-level install needs a restart	Run `get_mdg_from_runtime` and expect the live source and the right version. Check Specialize, Technologies, Manage Technology, and restart EA. See ea-mdg-deploy
An import call returns false	An id over 12 characters, an XML error or a dialog	Handle any error dialog in EA as described in Before you start, validate the XML and check every id for length
An element has a stereotype name but no profile binding	The technology was not loaded when the element was created, so EA recorded an ad hoc application	Confirm the technology is loaded, check with `summarize_stereotype_usage`, and re-apply the stereotype
A diagram of the right type has the wrong toolbox	The technology was not resolved when the diagram was created	Check the technology is loaded, then re-run `update_diagram` with the technology binding set to `MDGDgm=<technology>::<diagram stereotype>;`
Stale version: only you see the change, or Manage Technologies shows the old version	A file on the search path shadows the model copy, an application-level and a model copy both exist, or the model holds the id at both Location: Project and Location: Model and EA answers from the Project copy	Keep one copy per id. Remove the shadowing file or the Project copy, restart EA, and check Manage Technologies for a single entry at the expected version and Location
A technology reads as registered but not enabled	It is disabled in Manage Technologies. EA reports a disabled technology as loaded, so only the enabled flag shows it	Enable it in Manage Technologies (the assistant with computer use; otherwise you), then ask `get_mdg_from_runtime` again
An install into the model reports it is incomplete	A technology file imported into the model at Location: Project keeps profiles and diagram types but no toolbox pages	Install from an MDG Technology package at Location: Model, or use EA's Import to Model, then restart EA before judging the toolbox
An older build's profile may still be loaded after importing a new one	In some cases importing over an old build does not unload its profile	Retire old builds by disabling them in Manage Technologies, and put the version in the technology's description so builds can be told apart
The generated MDG shows no version, or a stale one	Generated files come out unversioned, and EA caches the first version it saw for a package	Always supply a version to `publish_package_as_profile`, and stamp the version on a generated file
A delete call returned true but the technology persists	The delete removes it from the registry, not from memory	Restart EA
The technology shows but the toolbox is empty	A toolbox page name does not equal the toolbox name in the diagram profile	Make them identical
A diagram type is missing from the New Diagram dialog	The diagram profile did not load, or the apply type is wrong	Use `Diagram_Logical`, not `Logical`
Tagged values do not appear	The stereotype name differs between the profile and the toolbox	The tag name must be `<TechID>::<StereotypeName>`, and the prefix must match the profile's documentation id
The MDG file is rejected on load	The encoding declaration and the bytes disagree	Declare `utf-8` and save as UTF-8
A technology you know is loaded is missing from the language or registered-technology lists	EA cannot enumerate technologies by automation. The lists are probes, and a technology disabled with no project copy looks unregistered	Ask by id with `get_mdg_from_runtime`, and check Manage Technologies
`get_embedded_mdgs` does not list a technology you know is loaded	The list shows only what the model stores, at Location: Project and at Location: Model. A technology loaded from a file on the workstation is not stored in the model	Ask by id with `get_mdg_from_runtime`, and read the Location in Manage Technologies
`assess_mdg_situation` says there is no client MDG, but one is loaded	It counts only languages it classifies as installed or embedded, and it has been reported to disagree with Manage Technologies	Treat the scenario as a hypothesis. Confirm with `list_registered_technologies` and `get_mdg_from_runtime`
A Quick Linker rule never fires	A constraint is unqualified	Qualify it as `<TechID>::<Stereotype>`, and test in EA's user interface
"Save Package as MDG Technology" is missing	The command is a step in EA's user interface that is not on every build	Check that the menu item exists on your build. Do it by hand, or let the assistant drive the interface if computer use is available

Diagrams

Symptom	Likely cause	What to do
The render does not reflect your changes	EA caches renders, or the change was made around EA (for example by SQL) and its session has not reloaded	Call `reload_diagram`, or ask for a refreshed render. `verify_diagram` always reloads before it renders. Then look at the picture
A diagram built by SQL looks stale in EA	EA's open session still holds the old rows	Reload the diagram, or reload the package in EA's Browser. That is a step in EA's window: the assistant does it with computer use, and otherwise you do
Connectors appear even with automatic connectors turned off	The setting controls what this call stores. EA still draws a relationship between two placed elements, and EA's own layout pass can write link rows	Place with no layout to guarantee no stored link, and lay out in a separate call. An instance id of 0 in `get_diagram` means "drawn, not stored". For a missing line, check both endpoints are placed and the connector exists
A color was set but is not drawn	EA echoes what was written, and some shapes own their fill (for example `Node` and `Grouping` in the ArchiMate 3 binding)	Render with `verify_diagram` including the SVG, and read the fill of the drawn element. Choose a concept that honors fill
A color set through EA's own dialog is not seen by a color rule	The rule reads the placement's own style, not the element's default appearance	Set the color through the per-diagram appearance operation
`update_diagram` wiped display settings or the technology binding	A raw style write replaces the whole string	Use `set_diagram_display`, `layout_diagram` or `set_custom_style`, which merge. Restore the technology binding if it was lost
An element is drawn wider than its stored rectangle	EA grows a drawn element to fit a name it cannot break, while the stored geometry keeps the old size	Use `verify_diagram` with the SVG to see the drawn size. Widen the box, or shorten the name. A 130 by 80 box holds about four short words
A check on stored rectangles calls a faithful diagram drifted	Stored geometry is not always where EA draws it (reported as tens of pixels in vendor-icon diagrams)	Judge by a render, not by stored rectangles
`find_icon` returns no useful match	A caption is not an icon name, or the glyph is not in the libraries (there is no plain AWS key, for one)	Search for the concept, not the caption. Try other wording, and say so when none exists. Do not substitute a near miss silently
An image or icon was set but nothing shows	A success report means the reference read back, not that EA drew it. Captions are also not drawn under images in exported PNGs, as reported	Render with `verify_diagram` and view it in EA
`layout_diagram` ignores the direction setting	EA's automation ignores it	Choose a layout style instead
Everything is stacked at the origin	Elements were placed from a bare id list with no layout	Supply geometry, let automatic layout run, or run `layout_diagram` afterward
Alignment is uneven after a layout or resize	Layout arranges but does not align	Run `neaten_diagram_objects`. Raise its tolerance for a diagram that drifted badly
Compartments or class attributes cannot be hidden	Compartments can only be reduced to names	Use the display settings that reduce them to names
A collapsed set of connectors reads as misleading	You must place the annotation yourself, and a collapse is per diagram	Place the returned annotation, or run `expand_parallel_connectors`
Double-clicking a navigation element opens its Properties, though the audit is clean	The composite marker is drawn, but in some EA builds double-clicking does not open the child diagram, though the audit passes	Test by double-clicking in EA. Do not rely on `find_composite_diagram_mismatches` alone. See Load a hierarchy and generate navigation diagrams
A navigation diagram is out of date after the hierarchy changed	A navigation set is a derived artifact	Regenerate it
The Visio export looks plain, and a hidden connector appears	The export is a rectangle per element with straight center-to-center lines, no stencils or waypoints, and it ignores the hidden setting	Re-skin in Visio. For a Visio diagram from scratch, use the separate AI Power Tools for Microsoft Visio product
A diagram response has no saved image path, or reports a preview error	Rendering failed, or the repository is a server connection or a cloud connection rather than a local file, so there is no folder to save beside	Call `get_diagram_png` with an explicit output path. The operation itself succeeded
A composed diagram reads as unclear though the linter reports it clean	The linter measures only known defects. It cannot judge whether the grammar was right	Render and look. Reconsider the grammar or split the content across diagrams. See ea-diagram-composition

Validation

Symptom	Likely cause	What to do
Zero violations on a model you know has problems	A selector one character off the stored stereotype selects nothing, and the response has no count of what was selected	Confirm the exact spelling with `summarize_stereotype_usage`. Write the unqualified name (`WBABusinessApplication`, not `WBA::WBABusinessApplication`). Prove each rule on a known-bad element
A rule never fires	The engine skips a condition type it does not recognize, or a selector and condition are paired wrongly, without an error	Use only the five supported condition types, each with its own selector type
A rule misses an element whose stereotype is not its first	Selectors may compare only the first stereotype	Select on the first stereotype, or restructure the rule
A package scope did not limit connector results, or a nonexistent package gave a clean pass	Connector rules and counts ignore the package scope, and a package id that does not exist scopes to nothing	Check the package id. Expect connector rules to run over the whole model
A blank tag is not reported	The tagged-value constraint checks only filled-in values	Pair it with a required-tag rule
An endpoint rule reports every connector	A connector-endpoint condition lists only targets or only sources, so the absent list is treated as empty	Give both lists
False positives from the ArchiMate 3.1 ruleset, especially in cross-layer rules	The grammar has no conditional, so a rule applies both endpoint lists to every connector it selects	Treat each violation as a candidate for review, and treat cross-layer results with particular caution. See ArchiMate 3.1 ruleset
The ArchiMate ruleset selects nothing	Only models built with EA's built-in ArchiMate technology are selected	Check the stereotype names in your model
The audit response is enormous, or the audit is slow	There is no cap or paging, and each rule issues queries per candidate	Scope with a package and run one rule group at a time

Reporting and Power BI

These apply to ea-reporting-database, ea-stakeholder-reporting and ea-power-bi. The operations are in Reporting business layer. The business layer is delivered as views in the EA database, as a separate reporting database or as Parquet files.

Symptom	Likely cause	What to do
A build is refused because rights are missing (`missing_rights`)	For views in the EA database, the account that runs the AI Power Tools MCP Server for Sparx EA lacks a right the build needs, such as creating views. Nothing was changed, and the reply names each missing right	Ask the database administrator for the rights named, or choose a separate reporting database or Parquet files
The reporting preflight stops the build (`preflight_blocked`)	A connector's stereotype is stored as qualified text, such as `WBA::Uses`, with no binding to the technology. Nothing was written	Fix it in EA after a baseline: re-apply the stereotype from the technology's toolbox or through the stereotype property (the assistant with computer use; otherwise you). Then run the reporting preflight again
The build is refused because the database holds an EA repository (`target_is_an_ea_repository`)	The reporting database named in the profile holds EA's own tables, and a rebuild there would overwrite them	Name a separate database in the profile
The build is refused because the database holds no EA repository (`not_an_ea_database`)	The profile for views in the EA database names a database that has no EA tables, or whose EA tables are not in the standard schema	Name the database that holds the EA repository
The operation does not match the profile (`wrong_path`)	The profile's delivery way is not the one the operation serves. The views build serves views in the EA database and a separate reporting database. The reporting-database build serves a separate reporting database and Parquet files	Use the operation that matches the profile
The layer is not reported as aligned	The alignment check counted a difference between the layer and the technology's metamodel	Read the counts before changing anything. If only the connectors outside every allowed combination are non-zero, the build is correct: those connectors use a declared connector stereotype between two element stereotypes the technology does not allow together, and the assistant tells you each combination and its count. Add the combination to the technology or fix the model. A missing table for an allowed combination, or a connector count that does not match, is a defect in the build: stop and report it
The value check reports differences	EA changed after a snapshot was built, or a tag value cannot sit in its typed column (a number in other than plain form is empty there)	Read which cells differ. For a snapshot, replay or rebuild and compare again. Spot-check the cells in EA
The value check compared zero cells	The check read nothing, for example because EA is not open on the repository the layer was built from. A check that read nothing fails	Open that repository in EA and run the check again
The check says the layer is not built (`not_built`)	A business table is missing	Build the layer, then check it
Replay is refused	No build has been made with this profile, so there is no kept extract, or the profile is for views in the EA database, which keep none	Run the reporting-database build first. Replay does not apply to views in the EA database
A refresh is refused (`already_running`)	A refresh of the same profile is already running	Poll the run id the reply gives
A refresh reports an unknown run (`unknown_run`)	The server restarted since the run began. Runs are held in memory	Start a new refresh and read its result
A build or refresh is refused in read-only mode (`readonly_mode`)	Building and removing the business layer are refused for every delivery way, and a refresh is refused for views in the EA database	Switch off Read-only mode on the extension's Configure screen (or remove `EA_MCP_READONLY` from the server's environment) if the write is intended, then restart the server
A call seems to hang during a build	A dialog is open inside EA	Handle the dialog as described in Before you start, then run the step again
Elements you expect are missing from the layer	An element with an empty stereotype is in no business table. A package the profile leaves out is not in scope	Run the governance gate before the build and decide per element. Check the scope in the profile
Governance gate: an element cannot be ranked	Several stereotypes extend its metaclass and nothing separates them	Choose from the list yourself. The assistant must not pick one. If the technology extends no stereotype for that metaclass, extend the technology or accept the exclusion
Governance gate: a stereotype you applied did not appear	The technology was not loaded, so EA recorded an ad hoc application. A success report does not mean the stereotype landed	Confirm the technology is loaded, apply the bare stereotype name, take the census again, and confirm the element is placed
A tag value is empty though the model shows one	Of two tags with one name on an element, the layer shows the first, as EA's Properties window does. A number in other than plain form is empty in a typed column	Check the reporting preflight's flags for duplicate tags, and the value check's differences
A spot check in EA disagrees with a snapshot by a few rows	Other work landed between the build and the check	Compare against the build's as-of time, and replay the build to see what it held
The Parquet step stops and asks for `pyarrow`	The Parquet files need the `pyarrow` package, which is not bundled	Install it for the Python the engines use, or choose another delivery way. CSV is never a substitute
The `.pbip` opens with no data	A generated project does not load data on open	Wait for the initial load, then refresh the data once in Power BI Desktop
Power BI reports a cyclic reference during a refresh	A refresh was started from the banner and from the ribbon at the same time	Wait for the initial load and press Refresh once
The `.pbip` stopped loading after files were moved	A Parquet project holds an absolute folder path specific to the machine	Regenerate the project at the new location. Do not edit it by hand
A Power BI project will not open and the message names no file	Power BI rejects the whole project on one violation, such as a description on a relationship or a model where EA's tables filter the business layer. A hand edit can reintroduce these	In the error, use "Copy details to clipboard" and read the inner exception. Regenerate
The model loads and the report fails to load	The report's theme is missing, as it can be in a hand-written report	Regenerate, and do not hand-write the report
A table visual is missing rows	A visual drops a row when every measure on it is blank, so an entity with no connectors in that direction disappears from a visual that shows only the measure	Show a column from the entity table beside the measure, or filter on the entity table
DirectQuery is slow	It queries the production database through the views	Use Import, or a separate reporting database
Power BI service refresh fails	A published model cannot refresh from local Parquet files	Refresh in Power BI Desktop
A roll-up is empty (zero elements, no groups)	There is no such stereotype, or no such tag on it, and the result cannot tell which	Check the stereotype name against `summarize_stereotype_usage` and the tag against the tag summary
A roll-up total is lower than the element count	Only elements that carry the tag are counted. A blank value is a group of its own, and comma-joined values under-count an exact roll-up	Compare the total with a plain count, roll up again with the values split when the multi-value count is not zero, and look for near-duplicate group values
A tag label does not resolve from `resolve_display_term`	A technology's tag aliases are not read from its MDG, and its stereotype aliases resolve only after its file has been parsed in the session	For a stereotype, take the alias from `get_mdg_from_runtime`. For a tag, split the camelCase name and drop the technology prefix
`generate_report` produced the wrong document	The template name is not validated, and an unknown name silently falls back to the default document	Open the output and check it. Name the output with `.rtf`
A figure to be quoted has no as-of time	A separate reporting database and Parquet files are snapshots	State the build's as-of time and its coverage with every quoted figure

Prolaborate

These skills drive the Prolaborate web interface in your signed-in browser session, through browser control. They need no server and no running EA. The assistant never enters credentials and never creates a session of its own. The order of causes below is the order the skill checks them. See prol-start-here.

Symptom	Likely cause	What to do
The page is the login screen, or turns into it mid-task	You are not signed in, or the session ended. The server can end a session	Sign in yourself and tell the assistant. It stops and does not retry, because re-driving a half-authenticated application creates duplicates
The assistant reports an expired token (ID2019)	The access token lives 240 seconds and is renewed only when the application navigates	Navigate within the application so it renews the token, then retry once
The assistant reports not permitted (ID2095)	You are authenticated but not permitted. This is a permissions answer, not a bug	Check the identity's role and Access Permissions
HTTP 422 with "'User Id' must not be empty"	The assistant holds a service token, not the signed-in user's	Re-read the key. The assistant must not substitute a registered application
Errors across Prolaborate that read like permission faults	The repository is inactive	Check the repository shows as `Active`
The screen is not where the skill expects	A newer Prolaborate moved a screen. The skills were verified against 5.6.1.40	Compare the running version (page footer or the health-check page). The assistant says which parts are unverified
An action returned 200 OK but nothing changed	Several Prolaborate endpoints return 200 OK with a failure flag in the body	The assistant reads the resulting state back after any change. Ask for that if it did not
You see more or less than a colleague	The skills were verified as a Super Admin, who skips authorization checks	Ask the assistant to state the identity it is acting as. A restricted user may see a smaller graph or matrix
A dashboard tile arrangement was not applied	The skill cannot arrange tiles, and a single click-drag is silently ignored by the grid	Arrange the layout yourself. The assistant hands you a layout plan
A widget could not be built (Lifecycle Road Map, Integration Reports)	Lifecycle Road Map needs a Life Cycle Management definition bound to a stereotype. Integration Reports needs an integration registered by the tenant owner, which needs external-system credentials	Provide the prerequisite. The assistant never enters external credentials and does not substitute another widget silently
A chart query disappeared	Changing a chart type wipes the query	Settle the type first, then build the query
A matrix link broke after a profile was renamed in EA	The profile name is the identifier	Select the matrix again by its new name
A matrix is huge or slow	There is no paging, and every element record is returned	No setting reduces the response. Plan for a large result, and read a smaller profile where one fits
An impact answer says "No results found", or the canvas is empty	Search filters the canvas, not the repository, so an empty canvas returns nothing for every search	Populate the canvas with the elements you want searched before you search
An impact answer is not complete	There is no depth traversal, so a multi-hop result is composed one hop at a time with a cap, and the relationship total is a floor when the cap was hit	Read the cap-hit indicator in the answer. Do not accept "everything affected"
A saved Analyzer view cannot be undone	A saved view is a tenant object with no undo	Create one only on request, and delete only what this session created

When to send a diagnostic report

Send one when the tables above do not explain the problem, or when a failure repeats. The assistant should escalate by itself after two failed attempts at the same thing, and whenever EA behaves inconsistently.

Ask Claude to run ea-diagnostic. It collects the system context, records each distinct problem with its severity, affected component, observed behavior, root cause (confirmed, marked "Suspected:", or under investigation), workaround and recommended fix, ranks them, and ends with submission instructions. It does not fix anything and does not send anything.
Turn on the server's diagnostics, then reproduce. Turn on diagnostics, which sets EA_MCP_DIAGNOSTICS to 1: in the Claude Desktop extension, switch on Enable diagnostic reports on its Configure screen, which also offers a report directory and a slow-call threshold; in VS Code, set eaMcp.diagnostics, and eaMcp.diagnosticsDir for the folder. Restart the server and repeat the failing step. A call that fails, errors or runs slowly (30 seconds by default) writes a Markdown report to %LOCALAPPDATA%\ea-mcp-server\diagnostics and returns its path. With diagnostics off, nothing is written. You can also raise the log level to DEBUG, INFO, WARNING or ERROR: with eaMcp.logLevel in VS Code, or with Log level on the Claude Desktop extension's Configure screen (default INFO). See Inside the server.
Review before you send. Nothing is sent automatically, and AI Power Tools has no telemetry. Both reports can contain element and package names and free text from your model. The server's report truncates strings over 500 characters, but names appear in full, and the ea-diagnostic narrative does not truncate. Distinguish "confirmed" from "Suspected:" before you send, because support relies on the difference.
Email it to help@novocircle.com. Use the subject format [Diagnostic] <short issue summary> — EA <version> — <date>. Attach the report file, and the server's diagnostic report if you had diagnostics on. Add the EA project file only if the issue is model-specific and you are comfortable sharing it, plus any MDG XML files involved and the server log if you have it.

Do not send credentials or tokens, a Prolaborate access token, or a model you are not permitted to share.

Before you send, check the common causes first: a dialog inside EA (see Connection to Enterprise Architect above), a technology that is installed but not loaded (see Modeling languages above), and an unverified write (see A write succeeded and nothing changed above). A blocking dialog in EA is not a defect in AI Power Tools.