Troubleshoot an OpenSimulator installation
Stepwise diagnosis: build, services, network, database and viewer.
Complete guide: read OpenSim / ROBUST logs
.NET build failure
Verify the .NET 8 SDK, not just runtime. Run runprebuild.sh at repository root and inspect dotnet build errors. Avoid DLLs built against incompatible releases.
Adapt this example: verify paths, hostnames, permissions and settings.
dotnet --list-sdks ./runprebuild.sh dotnet build --configuration Release OpenSim.sln
Logs to examine : Build console and dotnet build output; OpenSim.log may not exist until the application starts.
Messages to search (clues, not guaranteed errors) : Find the first build error, its project and reference, not just cascading failures.
Checks before changing anything : Check .NET SDK, runprebuild output, source revision and external DLLs.
Possible fix after confirmation : Fix the initial cause and rebuild without random dependency changes.
INI file not loaded
Make sure the file is OpenSim.ini or Robust.ini, not .example, .txt or in the wrong bin directory. Architecture includes must reference Common files actually created.
Logs to examine : OpenSim.log or Robust.log at startup, plus process-manager output if logging never starts.
Messages to search (clues, not guaranteed errors) : Look for config, ini, parse, missing and the first related file error.
Checks before changing anything : Check selected architecture, includes and working directory.
Possible fix after confirmation : Edit the correct INI; preserve previous logs before any required restart.
SQL connection refused
Check MySQL service, host, user, grants, password, authentication method and MySQL logs. Template values are not production credentials. Do not publish secrets in screenshots.
Logs to examine : Robust.log for central services; OpenSim.log for region; MySQL/MariaDB journal.
Messages to search (clues, not guaranteed errors) : Search connection refused, authentication, access denied, timeout and the first SQL error.
Checks before changing anything : Compare time, SQL host/port, privileges, database state and private networking.
Possible fix after confirmation : Fix the failing connection or service; do not expose SQL to bypass the issue.
ROBUST runs but regions cannot register
Check reachability of private service URIs from the simulator host, GridCommon.ini constants, ports, enabled services and logs on both ends.
Logs to examine : Both rejected region OpenSim.log AND Robust.log during the same registration attempt.
Messages to search (clues, not guaranteed errors) : Search grid service, region, register, refused, authentication, timeout and the earlier exception.
Checks before changing anything : Check GridServerURI, private URIs, DNS, firewall and connector readiness.
Possible fix after confirmation : Correct the failed URL or service and retry registration with a single change.
Unreachable address or port
Test from another machine. Binding 0.0.0.0 is insufficient if ExternalHostName advertises an unreachable private address or hostname. Expose only required region and public login ports.
Logs to examine : Region OpenSim.log, Robust.log when public/private endpoints are involved; system firewall logs.
Messages to search (clues, not guaranteed errors) : Search bind, address already in use, refused, timeout, unknown host.
Checks before changing anything : Check listening sockets, DNS, ExternalHostName, NAT and required TCP/UDP flows.
Possible fix after confirmation : Open only required flows and remove port conflicts.
Login works but avatar cannot enter
Separate authentication from region connectivity: login/ROBUST may work while the region UDP port is blocked or region registration is wrong. Compare timestamps in logs.
Logs to examine : Robust.log at authentication time and destination region OpenSim.log.
Messages to search (clues, not guaranteed errors) : Search login, agent, presence, seed, caps, teleport, timeout and the first failure.
Checks before changing anything : Separate successful authentication from failed region entry; verify UDP, NAT and advertised addresses.
Possible fix after confirmation : Fix the actual failing flow/service instead of resetting the avatar by default.
Hypergrid fails
Inspect Gatekeeper and HomeURI, published names and reachability from another grid. Switching Grid.ini to GridHypergrid.ini alone is insufficient.
Logs to examine : Origin/destination region OpenSim.log and involved grid Robust.log where accessible.
Messages to search (clues, not guaranteed errors) : Search gatekeeper, useragent, home, teleport, refused, timeout and authorization errors.
Checks before changing anything : Check URIs, certificates where used, DNS, public ports and HG modules.
Possible fix after confirmation : Fix HG configuration/routing and test both inbound and outbound travel.
Roll back safely
Back up INI files and databases, retain DLL copies and check hashes when available. After a failure, restore one previously consistent set rather than changing several layers at once.
Logs to examine : Preserve pre-incident logs and backup job logs.
Messages to search (clues, not guaranteed errors) : Identify the first change correlated with the failure and subsequent messages.
Checks before changing anything : Verify date, versions, integrity and backup coverage.
Possible fix after confirmation : Restore a validated consistent state while retaining evidence.