Platform > Dynamic Components

Troubleshooting Dynamic Components¶

This page lists the errors returned when editing the components file or managing a component, their causes, and how to resolve them.

Errors when editing the components file¶

These are reported when AmiCore parses data/ami.components. Each message includes the file path and the 1-based line number.

Message	Cause	Resolution
`Expected name;type;pwd at <path>:<line>: <line>`	The line has fewer than 3 semicolon-separated fields.	Write the line as `name;type;pwd`.
`Empty component name at <path>:<line>`	The `name` field is blank.	Provide a unique component name.
`Empty component type at <path>:<line>`	The `type` field is blank.	Provide a component type.
`Duplicate component name '<name>' at <path>:<line>`	The same name appears on more than one line.	Give each component a unique name.

Errors when adding or managing a component¶

These are returned by the ami console object.

Message	Cause	Resolution
`Component already exists: <name>`	A component with that name is already registered.	Choose a different name, or remove the existing component first.
`Component of type <TYPE> already exists at: <pwd>`	A component of that type already runs in that working directory.	Run the second component in its own working directory. See Run a second component of the same type.
`Component type not found: <TYPE> (existing types are ...)`	The type is not a known component type.	Use one of the listed types. See component types.
`Config File not found: <path>`	The 3-argument `addComponent` found no `config/root.properties` under the working directory. A directory that does not exist reports this same message, because the check is on the file.	Use the 4-argument `addComponent` to create the directory and its `config/root.properties`.
`Invalid component name: <name>`	The name is not a valid identifier. A hyphen is the common cause.	Use letters, digits, and underscores.
`pwd is required for this overload`	The 4-argument `addComponent` was called with an empty working directory.	Pass a working directory.
`Access denied by ami_<name>: <pwd> not in Permitted dirs (<list>)`	`ami.component.allowed.dirs` is set and the working directory falls outside it. Nothing is created.	Use a directory inside the list, or widen `ami.component.allowed.dirs`.
`required property missing: <key>`	The `properties` argument of the 4-argument `addComponent` omits a property the component type requires. Keys are reported one at a time.	Add the key and retry. See the port warning in Run a second component of the same type.
`Error loading public keys: <path>`	A transient copy has no `keys/3forge.pub`, which a clone does not inherit.	Pass the source key paths in `optionsOverride`. See Create a transient component.
`Component not found: <name>`	The named component is not registered.	Check the name with `ami.showComponents()`.
`Component is already running: <name>`	`startupComponent` was called on a running component. On a `GATEWAY` this also appears after a successful shutdown, because a Gateway keeps reporting `RUNNING`.	For a Gateway, use `ami.reloadComponent(name)`. See Managing components.
`Component is already shutdown: <name>`	`shutdownComponent` was called on a component that is already stopped.	Check the `Status` column with `ami.showComponents()` first.
`Component is not transient: <name> (use removeComponent instead)`	`removeTransientComponent` was called on a persistent component.	Use `ami.removeComponent(name)` for a persistent component.

AmiCore will not start¶

An entry in data/ami.components that cannot be started is fatal at startup. AmiCore logs the failure and exits before any component starts, so the whole deployment stays down rather than the one component:

Shuting down due to fatal error on startup
java.lang.RuntimeException:Entry starting up component in <path>\data\ami.components
 caused by java.lang.RuntimeException:Missing directory: <pwd>
EXITING WITH CODE 3.  Unknown Error: RuntimeException

Missing directory: <pwd> is the common cause: a line names a working directory that does not exist. The same entry on a running deployment affects only its own component, so an edit that looked harmless can prevent the next start.

To recover, correct or remove the offending line in data/ami.components and start AmiCore again. The file is plain text and can be edited while the process is down.

`ami.showComponents()` returns an internal error¶

A showComponents() call can fail outright:

1	`ERROR: Internal Error: NullPointerException`

This happens when data/ami.components declares a component that is not registered, which is the state left by an entry that failed to start on a running deployment. The command that would report the failed component is the one that fails, so an estate that is merely misconfigured looks unreachable.

Other commands are unaffected. Use ami.showPorts() to see which components still hold their ports, and compare that against data/ami.components to find the entry that did not start. Correcting the entry restores both the component and showComponents() on the next poll.

Admin console connection issues¶

The admin console is a custom command channel reached over ssh, not a standard shell, and it differs from a normal ssh session in 3 ways:

The account in the startup line is the shipped default, not the configured one. output.log prints ssh -p 3285 user@<host>, naming the account a new deployment ships with. The line is not regenerated when the accounts change, so on a deployment using different accounts it returns Access denied. The port and host in the line stay correct.
The exit word is quit. The word exit is not recognized and returns Unknown variable: exit.
A scripted client must send carriage-return (\r) line terminators. A client that sends line-feed (\n) only can concatenate commands so that none run. This affects automated clients, not an interactive ssh session.

If the console's host key has changed, an ssh client may refuse to connect from a cached key. Update the cached key for the host, or pin the current key fingerprint in the client.

A file edit is not taking effect¶

If an edit to data/ami.components does not start or stop a component:

Confirm polling is enabled. When ami.components.check.config.file.changes.period.ms is 0, file edits are applied only on the next restart. See Reload polling.
Allow for the poll interval, 5 seconds by default, before the change is detected.
Apply the change through the admin console instead, which takes effect immediately.