OpenSimulator · EN

Troubleshooting archives, assets and regions

From symptom to probable cause, with concrete checks before attempting repairs.

Start by checking logs. Do not restart or purge data before preserving the first relevant failures.

OpenSim and ROBUST log guide

OAR loaded but textures are missing

Check whether the OAR was saved with --noassets or loaded with --skip-assets. Check referenced UUIDs in the asset service and warnings in logs. Retry with a full archive if you have the needed rights and files.

Logs to examine : Destination region OpenSim.log and central Robust.log for a grid; Standalone uses OpenSim.log.

Messages to search (clues, not guaranteed errors) : Search the archive name, asset UUID, read/storage errors and OAR load events; exact messages vary by version.

Checks before changing anything : Compare import/export options and verify asset retrieval for a specific UUID without changing data.

Possible fix after confirmation : If assets were intentionally excluded, use a complete trusted archive after backing up the target.

Read-only check: adapt paths, service names and values.

grep -nEi 'asset|oar|archive|exception|error' OpenSim.log | tail -n 80

Builds appear displaced or outside the region

Check region SizeX/SizeY first, then --displacement and --rotation. Validate destination boundaries before reimporting. An OAR does not rewrite Regions.ini dimensions for you.

Logs to examine : OpenSim.log during the OAR import.

Messages to search (clues, not guaranteed errors) : Locate the load operation and any warnings about dimensions or skipped objects.

Checks before changing anything : Compare source/destination sizes, displacement, rotation and Regions.ini coordinates.

Possible fix after confirmation : Retry on a test region with corrected options after backup.

Read-only check: adapt paths, service names and values.

grep -nEi 'oar|rotation|displacement|region|warn|error' OpenSim.log | tail -n 80

Import replaced existing objects

A restore without --merge can replace substantial target content. Stop edits, retain logs and recover from the pre-import backup. Avoid uncontrolled additional merges.

Logs to examine : Affected region OpenSim.log and any backup job logs.

Messages to search (clues, not guaranteed errors) : Find the import time and OAR loading messages; confirm the actual options used.

Checks before changing anything : Determine whether --merge was missing and inventory earlier backups.

Possible fix after confirmation : Stop further changes; restore only a consistent snapshot validated on a test environment.

Read-only check: adapt paths, service names and values.

grep -nEi 'oar|load|archive|error' OpenSim.log | tail -n 100

IAR backup is incomplete

Verify inventory path, --exclude and --excludefolder, --perm filters and missing assets. --skipbadassets may omit broken items; it is not a repair tool.

Logs to examine : OpenSim.log from the IAR processing instance and Robust.log if inventory is remote.

Messages to search (clues, not guaranteed errors) : Look for IAR, inventory, permission, asset, UUID and serialization errors.

Checks before changing anything : Compare requested inventory path, exported contents and exclusion flags.

Possible fix after confirmation : Retry a targeted export without unnecessary filters; --skipbadassets is not a repair.

Read-only check: adapt paths, service names and values.

grep -nEi 'iar|inventory|asset|permission|error' OpenSim.log | tail -n 100

Assets were omitted from an IAR

An IAR created with --noassets retains references but not asset payloads. The target must already provide the referenced assets. Re-export with assets from the source if still possible.

Logs to examine : OpenSim.log during export and import; Robust.log for remote asset services if available.

Messages to search (clues, not guaranteed errors) : Search IAR events, missing-asset errors, retrieval failures and affected UUIDs; wording depends on version.

Checks before changing anything : Inspect backup options and check whether the destination asset service has the UUIDs.

Possible fix after confirmation : Re-export with assets from the source if available.

Read-only check: adapt paths, service names and values.

grep -nEi 'iar|asset|not found|error' OpenSim.log | tail -n 100

INI edit appears ineffective

Check that you edited the active file, not an .example template. Inspect bin/config overrides and config-include files. Use config show and check whether a restart is needed.

Logs to examine : Target simulator OpenSim.log; Robust.log if the change concerns central services.

Messages to search (clues, not guaranteed errors) : Find configuration file loading events, parse errors and unrecognized sections or keys.

Checks before changing anything : Compare actual files, includes and effective configuration through simulator config show.

Possible fix after confirmation : Correct only the active file and restart the relevant component if it requires configuration reload.

Read-only check: adapt paths, service names and values.

grep -nEi 'config|ini|error|warn' OpenSim.log | tail -n 80

Region memory usage is high

Measure the trend over time and compare equivalent activity. Check caches, scripts and objects. High RSS alone does not prove a leak; look for persistent growth at similar load.

Logs to examine : OpenSim.log and system logs (OOM, kill, swap); memory metrics.

Messages to search (clues, not guaranteed errors) : Look for OutOfMemory, memory, GC or abrupt termination; do not conclude a leak from one RSS snapshot.

Checks before changing anything : Compare RSS and activity over time, scripts, physics, cache and swap.

Possible fix after confirmation : Isolate the responsible subsystem before tuning or restarting; preserve metrics.

Read-only check: adapt paths, service names and values.

grep -nEi 'memory|OutOfMemory|exception|fatal' OpenSim.log | tail -n 80
journalctl -k --since '1 hour ago' | grep -Ei 'oom|killed process|out of memory'

Teleports are slow

Inspect source and destination region logs, DNS resolution, ROBUST services, database, network exchanges and module calls. Do not automatically blame the physics engine.

Logs to examine : OpenSim.log from BOTH source and destination regions; Robust.log for a grid.

Messages to search (clues, not guaranteed errors) : Find transfer timestamps, timeout, failed, destination, agent and exceptions.

Checks before changing anything : Align clocks, correlate stages and measure which phase is slowest.

Possible fix after confirmation : Fix the failing layer (network, services, region or modules) rather than blindly changing physics settings.

Read-only check: adapt paths, service names and values.

grep -nEi 'teleport|transfer|timeout|exception|failed' OpenSim.log | tail -n 100

OpenSimulator Wiki — Performance