Common problems during package install or update
Companion's software management interface is called the Xanadu Package Service (XPS) client, known by the script name _xanadu-client. It is a highly visible system component that was converted into a system library module throughout the course of development of version 8.5. Because it is not part of the system's day-to-day operation but essential to proper maintenance, using it can be stressful, especially when it behaves unexpectedly or incorrectly. This article describes common problems with the package manager, including error messages and other situations only found in old versions of the OS, and various recommended solutions.
For general instructions on how to use the software management menu and the xanadu system command, see managing packages and installed software.
Problem: In Companion 8.6 and later, the error message may appear during package installation or upgrade:
Explanation: This indicates that the package manager believes the address of user memory (see also installing data files) is a prim link number below 2. This usually means that the package manager was never given the address of the memory card by the configuration manager. It may also indicate that the memory card is missing, such as if the system memory prim has been unlinked. Alternatively, the configuration manager may have skipped memory card detection due to an event queue flood.
Context: Like other system libraries, the package manager is reset automatically after every teleport. This reduces the amount of script memory the region servers need to transmit during the region crossing. However, script events can be unreliable or disordered following a region change, causing some messages to never arrive. If you have encountered the error message [_balance]: Script Error: Stack-Heap Collision since you last changed regions, then it is almost certain that the configuration manager (the "_balance" in question) is not working reliably.
Solution: In most cases, the system command reset xanadu-client will suffice to force the package manager to retrieve the correct link number from the configuration manager, in which case you can reconnect to the package server and attempt the installation or upgrade again.
Alternatives: The command conf _hwaddr.program will report "Not found: ��.program" if the configuration manager failed to detect the memory card link number. The disk check (8.6.1) or file check (8.6.2 and later) commands will ensure the link number is set correctly. Finally, reset balance will restart the configuration manager itself.
Problem: during package installation or upgrade, you see the message:
Context: To prevent script injection, SL requires that any attempt to copy a script from one prim to another (such as from a Xanadu install disk to an NS main controller) be accompanied by a 32-bit private key called a "pin". During installation or upgrade, the package manager provides the installer with a public key, from which it derives the actual pin value using a secure method. The public key is randomized frequently and is unique to each controller, so the package manager needs to have the latest value for package installation to be possible. However, since the package manager resides in system memory and scripts can only set the number for their own prim, the public key must be transferred to it from user memory. This interdependence exposes the same structural weaknesses described in the context section of the memory card detection failure scenario, above.
Solution: The system command reset xanadu-client is usually sufficient.
Alternatives: disk check (Companion 8.6.1, Clockwork 8.6.2) or file check (Companion 8.6.2 and later) can be used to re-establish the memory card link number and update the pin. This command outputs the message "Reinitialized memory card security identifier." upon success. Failure may also be caused by a crash in _songbird (the disk driver script), in which case the check command will produce no output. The _songbird script has no fail-safe mechanism and must be reset manually using the viewer's Edit tools window if it crashes. (Most customers may prefer to simply seek a redelivery of their controller at this point.)
Problem: The xanadu system command usually or totally fails to act in response to user input. Menus are unusable.
Explanation: Several development builds of Companion 8.6.0 from 2020 had experimental session timeout code that caused the package manager to hibernate prematurely due to a bug.
Solution: Touch the white Xanadu Upgrade Assistant monolith at the Nanite Systems Research Campus location in Eisa. It will provide a replacement copy of the _xanadu-client script and guide you through the process of installing it.
Alternatives: Seek a controller redelivery. These OS versions are no longer easily obtained.
Problem: The Companion update package reports the following when used:
Explanation: The package's inventory contents changed while it was owned by an avatar with the wrong UUID. To help ensure OS updates are authentic, the system updater script must be reset if it is modified by an avatar other than the intended recipient or d69ca06e-aa22-49e4-86e1-42677e26f3f5.
Context: This problem is easy to fix, but you should stop and reflect on why you're encountering it.
Solution: Travel back in time to a point before rhet0rica was hit by a bus.
Alternatives: Stop trying to distribute malware disguised as an OS update.
Problem: The software menu and xanadu servers command both list no servers, and the xanadu search command accomplishes nothing.
Explanation: Package servers can only be accessed from the region in which they are located. A list of store and service locations is available online. Note that different OS distributions (i.e., Clockwork, Wetware, ATOS/D, Lux, and ATOS/CX) have separate servers and cannot access Xanadu package servers made available for other distributions.
Alternatives: Depending on the package in question, it may be possible to cache the item on one controller, transfer the installer to your desired platform, and unpack it there. The package cache is in the controller's system memory (the root prim) and is easily accessed. Additionally, it may be the case that the package manager is hibernating prematurely; if you are on a pre-release of Companion 8.6, see "Package manager unresponsive," above.
Problem: A device firmware update package reports the following when used:
Context: The public key (see Context section of "Script loading problems", above) is a 32-bit number used to generate a secret value that is required for script updating. Unlike with OS or software package updates, the private key is generated through a method known only to the installer package and the device itself.
Solution: If you are certain the update has been tested with your version of the peripheral in question, run device probe to refresh the package manager's cache of devices and their public keys.
Alternatives: Wait for this feature to be finished. (As of this writing, it isn't.)
Problem: Package upgrades (especially OS upgrades) fail, even though a package with a newer version number is on the server. Error messages may include:
Explanation: Two distinct problems cause this to appear. Companion 8.6.0 and 8.6.1 exhibited a bug where the OS version number would be discarded by the package manager whenever it refreshed the package list, including when connecting to a server. Separately, some Xanadu package servers require restarting after updated packages are loaded into them using automatic superseding (deletion of old versions upon detecting a new version).
Solution: The OS package for Companion is also available under the package name System during most releases. This avoids the problem of version masking and appears to the package manager to be a normal package that can be installed. If the issue affects a non-OS package, simply restart the package server responsible.
Alternatives: Caching packages may sometimes bypass these issues. Separately, early versions of the package server, which do not feature automatic superseding, are capable of holding multiple packages with the same name but different version numbers; these are available to existing XPS owners upon request to rhet0rica.
For general instructions on how to use the software management menu and the xanadu system command, see managing packages and installed software.
important: running system commandsSystem commands are also known as @ commands, and with good reason: a unit can run a system command by prefixing @ and speaking in local chat while chat is captured. For example, typing @reset xanadu-client will perform the reset described above. If you have disabled the chat redirect, you must re-enable it with /1capture first. If you are unable to do this, chances are that either self access is disabled, or you forgot to turn RLVa on in your viewer.
If for some reason you cannot use the normal input handler, you can alternatively send commands through local command access or remote command access. In these cases the @ is not used.
If for some reason you cannot use the normal input handler, you can alternatively send commands through local command access or remote command access. In these cases the @ is not used.
Memory card detection failure
Problem: In Companion 8.6 and later, the error message may appear during package installation or upgrade:
Package install failed. PANIC: Memory card detection failed. Run 'file check' and try again.Equivalently, 'file check' may be replaced with 'disk check', or the advice about running an instruction may be entirely absent. You may also see a message like:
WARNING: Memory card address not set correctly. Please reset or fix memory card.This message generally appears when connecting to a package server.
Explanation: This indicates that the package manager believes the address of user memory (see also installing data files) is a prim link number below 2. This usually means that the package manager was never given the address of the memory card by the configuration manager. It may also indicate that the memory card is missing, such as if the system memory prim has been unlinked. Alternatively, the configuration manager may have skipped memory card detection due to an event queue flood.
Context: Like other system libraries, the package manager is reset automatically after every teleport. This reduces the amount of script memory the region servers need to transmit during the region crossing. However, script events can be unreliable or disordered following a region change, causing some messages to never arrive. If you have encountered the error message [_balance]: Script Error: Stack-Heap Collision since you last changed regions, then it is almost certain that the configuration manager (the "_balance" in question) is not working reliably.
Solution: In most cases, the system command reset xanadu-client will suffice to force the package manager to retrieve the correct link number from the configuration manager, in which case you can reconnect to the package server and attempt the installation or upgrade again.
Alternatives: The command conf _hwaddr.program will report "Not found: ��.program" if the configuration manager failed to detect the memory card link number. The disk check (8.6.1) or file check (8.6.2 and later) commands will ensure the link number is set correctly. Finally, reset balance will restart the configuration manager itself.
Script loading problems
Problem: during package installation or upgrade, you see the message:
Task <package> trying to illegally load script onto task <system>!(Where <package> is the name of the package being installed and <system> is the name of your controller or user memory prim.) Equivalently, the OS or system add-on installation process may hang at:
[Stage 0] Beginning memory card update. If the updater stalls at this step or you see an error message about illegal script loading, reset your package manager and try the upgrade again.For other packages, installation may hang silently after a message such as:
Requesting removal of old package... Installing assets... Installing scripts...Explanation: The package manager has the wrong pin, which is a 32-bit private key required to install scripts.
Context: To prevent script injection, SL requires that any attempt to copy a script from one prim to another (such as from a Xanadu install disk to an NS main controller) be accompanied by a 32-bit private key called a "pin". During installation or upgrade, the package manager provides the installer with a public key, from which it derives the actual pin value using a secure method. The public key is randomized frequently and is unique to each controller, so the package manager needs to have the latest value for package installation to be possible. However, since the package manager resides in system memory and scripts can only set the number for their own prim, the public key must be transferred to it from user memory. This interdependence exposes the same structural weaknesses described in the context section of the memory card detection failure scenario, above.
Solution: The system command reset xanadu-client is usually sufficient.
Alternatives: disk check (Companion 8.6.1, Clockwork 8.6.2) or file check (Companion 8.6.2 and later) can be used to re-establish the memory card link number and update the pin. This command outputs the message "Reinitialized memory card security identifier." upon success. Failure may also be caused by a crash in _songbird (the disk driver script), in which case the check command will produce no output. The _songbird script has no fail-safe mechanism and must be reset manually using the viewer's Edit tools window if it crashes. (Most customers may prefer to simply seek a redelivery of their controller at this point.)
Package manager unresponsive
Problem: The xanadu system command usually or totally fails to act in response to user input. Menus are unusable.
Explanation: Several development builds of Companion 8.6.0 from 2020 had experimental session timeout code that caused the package manager to hibernate prematurely due to a bug.
Solution: Touch the white Xanadu Upgrade Assistant monolith at the Nanite Systems Research Campus location in Eisa. It will provide a replacement copy of the _xanadu-client script and guide you through the process of installing it.
Alternatives: Seek a controller redelivery. These OS versions are no longer easily obtained.
Modified OS installer
Problem: The Companion update package reports the following when used:
Unauthorized modification to system update card detected. Cannot continue.
Explanation: The package's inventory contents changed while it was owned by an avatar with the wrong UUID. To help ensure OS updates are authentic, the system updater script must be reset if it is modified by an avatar other than the intended recipient or d69ca06e-aa22-49e4-86e1-42677e26f3f5.
Context: This problem is easy to fix, but you should stop and reflect on why you're encountering it.
Solution: Travel back in time to a point before rhet0rica was hit by a bus.
Alternatives: Stop trying to distribute malware disguised as an OS update.
No servers
Problem: The software menu and xanadu servers command both list no servers, and the xanadu search command accomplishes nothing.
Explanation: Package servers can only be accessed from the region in which they are located. A list of store and service locations is available online. Note that different OS distributions (i.e., Clockwork, Wetware, ATOS/D, Lux, and ATOS/CX) have separate servers and cannot access Xanadu package servers made available for other distributions.
Alternatives: Depending on the package in question, it may be possible to cache the item on one controller, transfer the installer to your desired platform, and unpack it there. The package cache is in the controller's system memory (the root prim) and is easily accessed. Additionally, it may be the case that the package manager is hibernating prematurely; if you are on a pre-release of Companion 8.6, see "Package manager unresponsive," above.
No upgradable device
Problem: A device firmware update package reports the following when used:
No upgradable device at address '<device>'. Cannot continue.Explanation: The package manager never received the public key for the device you are trying to upgrade. This may indicate the device cannot be upgraded (perhaps the update package is for a different device that uses the same address?) or that the device manager simply needs to send the information to the package manager again (see Context section of "Memory card detection failure", above).
Context: The public key (see Context section of "Script loading problems", above) is a 32-bit number used to generate a secret value that is required for script updating. Unlike with OS or software package updates, the private key is generated through a method known only to the installer package and the device itself.
Solution: If you are certain the update has been tested with your version of the peripheral in question, run device probe to refresh the package manager's cache of devices and their public keys.
Alternatives: Wait for this feature to be finished. (As of this writing, it isn't.)
No useful version on server
Problem: Package upgrades (especially OS upgrades) fail, even though a package with a newer version number is on the server. Error messages may include:
Already installed: <package> (no useful version on server) Package not found on server: <package>Additionally, the command xanadu list may report the OS version as Companion_??? or similar.
Explanation: Two distinct problems cause this to appear. Companion 8.6.0 and 8.6.1 exhibited a bug where the OS version number would be discarded by the package manager whenever it refreshed the package list, including when connecting to a server. Separately, some Xanadu package servers require restarting after updated packages are loaded into them using automatic superseding (deletion of old versions upon detecting a new version).
Solution: The OS package for Companion is also available under the package name System during most releases. This avoids the problem of version masking and appears to the package manager to be a normal package that can be installed. If the issue affects a non-OS package, simply restart the package server responsible.
Alternatives: Caching packages may sometimes bypass these issues. Separately, early versions of the package server, which do not feature automatic superseding, are capable of holding multiple packages with the same name but different version numbers; these are available to existing XPS owners upon request to rhet0rica.