Troubleshooting

Actor fails to replicate

If you’ve set up your Actor for replication according to the Unreal Engine documentation, but your Actor does not replicate, here are some things to try:

  • It’s easy to forget to generate the schema for your replicated Actor. Make sure you generate schema before you run your project.
  • Your game needs to create an Actor on server-worker instances before the Actor can replicate to client-worker instances. Check the process in Unreal's Actor replication documentation.
  • Ensure that your call to SpawnActor is happening on your server-worker instance.
  • Validate that the entity that represents your Actor appears in the Inspector. If it doesn't, then the Actor is probably not correctly marked for replication.
  • Mark your Actor for replication as described in Unreal's Actor replication documentation. You can validate that your Actor is replicated in USpatialNetDriver::ServerReplicateActors.
  • Validate that you receive a WORKER_OP_TYPE_ADD_ENTITY message for the entity representing your Actor in the USpatialView::ProcessOps and that your entity is spawned in USpatialReceiver::CreateActor.

Crash when starting PIE instance

If you have moved your game over to the SpatialOS GDK for Unreal and the game crashes in UEngine::TickWorldTravel when starting a PIE instance, try the following:

  1. In the Unreal Editor, go to Edit > Project Settings > Project > Maps & Modes > Game Instance Class.
  2. Ensure that you have set your Game Instance Class to point to either SpatialGameInstance or a game instance that inherits from USpatialGameInstance.
  3. Save your settings and restart the PIE instance.

Switch networking stack

In general you will use Unreal Engine’s networking stack, but you can switch between the Unreal Engine and SpatialOS GDK for Unreal networking stacks to suit your testing requirements.

In the Unreal Editor, select the Play drop-down menu from the Unreal toolbar, and use the SpatialOS Networking check box to switch between the two networking stacks.


Compilation error when building the GDK

You see this compilation error when you try to build the GDK:

Error C2248: FRepLayout::Cmds': cannot access private member declared in class 'FRepLayout.

This error indicates that you’re building against an unsupported version of Unreal Engine.

Make sure you're targeting the fork of Unreal Engine that the GDK requires. See the setup guide for details.


Unsupported multicast RPCs

If you're wondering why the SpatialOS GDK for Unreal doesn't support the multicast RPCs you use in your game, this is because:

  • Multicast RPCs use SpatialOS events, which can only be sent unreliably.
  • The cost of multicast RPCs scales with the number of client-worker instances present in a deployment, so they can become very expensive.

A better approach is to send RPCs to only the worker instances that are close to the broadcasting worker instance.


Project build error

You see the following error when you build your project:

Unknown class specifier 'SpatialType'

SpatialType is a class specifier used to tag classes to replicate to SpatialOS. This message means that you have not built the UE4 fork, or pointed your project to use it.

Follow the instructions in Get Started to ensure the GDK is set up correctly.


Error starting SpatialOS deployment

When you start your SpatialOS deployment, you see errors similar to the following:

uses component ID 100005 which conflicts with components defined elsewhere.

This indicates that you have been using the GDK since a pre-alpha release. To resolve the problem:

  1. Delete the contents of your spatial/schema folder.
  2. Run Setup.bat in the GDK folder.
  3. Re-generate the schema.

Setup.bat error

When you run Setup.bat you see the following error:

error MSB3644: The reference assemblies for framework ".NETFramework,Version=4.5" were not found.

The full error message is as follows:

C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\MSBuild\15.0\bin\
Microsoft.Common.CurrentVersion.
targets(1179,5): error MSB3644: The reference assemblies for framework ".NETFramework,
Version=4.5" were not found. To resolve this, install the SDK or Targeting Pack for 
this framework version or retarget your application to a version of the framework 
for which you have the SDK or Targeting Pack installed. Note that assemblies will 
be resolved from the Global Assembly Cache (GAC) and will be used in place of reference 
assemblies. Therefore your assembly may not be correctly targeted for the framework 
you intend. 
[C:\MyProject\Game\Plugins\UnrealGDK\SpatialGDK\Build\Programs\Improbable.Unreal.
Scripts\Build\Build.csproj]

This error indicates that Visual Studio is missing some dependencies.

To add the missing workload, run the Visual Studio installer and click Modify on your existing installation. Install the Universal Windows Platform development workload, which includes the .NET Framework 4.5.


Worker instances disconnect from the SpatialOS Runtime

When debugging your game, you see log messages similar to the following:

LogNet: UNetConnection::Cleanup: Closing open connection. [UNetConnection] RemoteAddr: , 
Name: SpatialNetConnection_14, Driver: GameNetDriver SpatialNetDriver_17, IsServer: 
YES, PC: BP_PlayerController_C_0, Owner: BP_PlayerController_C_0, UniqueId:

This is caused by a known issue in the GDK's connection heartbeating logic that disconnects worker instances that have stopped responding.

To work around the issue:

  1. In the Unreal Editor, go to Edit > Project Settings > Runtime Settings.
  2. Update the Heartbeat Timeout value from the default 10 seconds to a much larger value that you're unlikely to reach when debugging, for example 10000.
  3. Go to Edit > Project Settings > Editor Settings.
  4. In the Launch section, make sure the Legacy Flags section includes an entry to set bridge_qos_max_timeout to 0.

When you've finished debugging your game and you want to deploy it locally or in the cloud, set these values back to their defaults so that failing worker instances are correctly disconnected from the SpatialOS Runtime.


Schema match error

When you run your client you see the following error:

Your client's schema does not match your deployment's schema. Client hash: '%u' Server hash: '%u'

If you continue without updating the schema, then the mismatching schema might cause problems that are hard to investigate. For example, if you have added a component to the schema but have not uploaded the component to the cloud, your server-worker instance could receive a cross-server RPC with a parameter that it cannot resolve.

To avoid this problem, generate the schema again before uploading the new assembly. This is so that the assembly includes the latest schema.

Note: Usually a mismatching schema is created when you build your worker manually. When you use the automated tools such as BuildWorker.bat, you are unlikely to have this problem because the same schema is used to build both client and server-workers.

Note: This error is only displayed in the development build of your game. The client does not display the error in the release build of your game.


Multiple Runtime instances

You can only run one instance of the SpatialOS Runtime. If there is an instance of the SpatialOS Runtime running with a project and you try to run another project, a warning dialog box appears.

Click Yes to stop the instance and then start the Runtime for your current project.


Error starting local deployment

When you try to start a local deployment you see the following errors:

Could not resolve bundle version
Access token is expired

To resolve the problem:

  1. Run spatial auth logout to clear your local credentials.
  2. Run spatial update to update your SpatialOS CLI.
  3. Start the local deployment again.

See Reference for more information on these commands.


Client executable fails to start

Your client fails to start and you see the following error:

ClientError: Your client executable failed to start
This is probably an issue with your client executable

This might indicate that a dependency of the executable is missing. Ensure that you have installed all required software as outlined in Get the dependencies, particularly the Visual Studio package Desktop development with C++.


2020-10-06 Page updated with editorial review: added client executable fails to start
2020-09-10 Page updated with editorial review: added error starting local deployment
2020-08-04 Page updated with editorial review: rewrote all troubleshooting entries
2019-04-15 Page updated with limited editorial review: added schema mismatch troubleshooting
2019-07-02 Page updated with limited editorial review: added debug workaround

Updated 11 months ago


Troubleshooting


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.