Changes to Assetdatabase APIs when called during import

Unity Engine
, , , , , , ,
1

Changes to Assetdatabase APIs

We’re making changes to improve the reliability and determinism of Unity’s asset import system. Starting with Unity 6000.3.0b2, you’ll see warning messages when certain AssetDatabase APIs are called during importing.
These warnings will become exceptions in Unity 6.4.

The Change

In release 6000.3.0b2 we have introduced a warning message, triggered when one of the listed APIs is called during an import.

Example of the warning generated when ImportAsset is called during importing:
“Calls to “AssetDatabase.ImportAsset” are restricted during asset importing. Please make sure this function is not called from ScriptedImporters or PostProcessors, as it is a source of non-determinism. This warning will eventually become an exception.”

As stated in the warning message, this warning will become an exception in 6.4, so this is meant to give users a release to fix their code before the APIs are deprecated.

Asset Import API Protection Overview

The following table provides an overview of the different APIs and their protection levels across relevant Unity versions. Historically the protection level has varied depending on whether the asset is being imported on the asset import worker (with parallel import) or the main editor process.

Version Reference:

  • Before 6.3: Versions prior to 6000.3.0b2
  • 6.3: Unity 6000.3.0b2
  • 6.4: Future version (TBD)

Protection Levels:

  • non: API calls are allowed without restrictions

  • warning: API calls generate warnings but proceed

  • exception: API calls throw exceptions and fail

  • error: API calls generate errors

    API Method Before 6.3 Worker Before 6.3 Editor 6.3 Worker 6.3 Editor 6.4 Worker 6.4 Editor
    CreateAsset exception warning exception warning exception exception
    ImportAsset non non warning warning exception exception
    DeleteAsset exception non exception warning exception exception
    DeleteAssets exception non exception warning exception exception
    MoveAsset exception non exception warning exception exception
    ExtractAsset non non warning warning exception exception
    RenameAsset exception non exception warning exception exception
    MoveAssetToTrash exception non exception warning exception exception
    MoveAssetsToTrash exception non exception warning exception exception
    CopyAsset exception non exception warning exception exception
    CopyAssets exception exception exception exception exception exception
    SaveAssets exception error exception warning exception exception
    SaveAssetIfDirty non non warning warning exception exception
    SetLabel non non warning warning exception exception
    ClearLabels non non warning warning exception exception
    Refresh exception error exception error exception exception
    StartAssetEditing exception error exception error exception exception
    StopAssetEditing exception error exception error exception exception

Why these APIs are problematic while importing

Unity caches import results in the Library folder (or cache server) to avoid unnecesary re-imports of unchanged assets.
However, this cache only stores the direct outputs of the import; it doesn’t capture side effects.

Here’s the problem:

  1. First import: Your importer runs and creates side effects (new assets, modifications, etc.)
  2. Cached import: Unity uses the cached result, but the side effects don’t run again
  3. Cache invalidation: When dependencies change, Unity re-runs the import and the side effects execute again

This creates non-deterministic behavior: sometimes your side effects run (fresh imports), sometimes they don’t (cached imports). The same project state can produce different results depending on cache status.

Example scenario:

  • Import creates a texture and also calls CreateAsset to generate a material.
  • On cached import: texture loads from cache, but material creation is skipped.
  • On fresh import: both texture and material are created.
  • Result: inconsistent project state depending on cache.

This is why Unity will restrict these APIs during imports to enforce determinism.

Workaround

But what if I really want to have some side effect triggered when an import happens?

You can use the AssetImportContext.GetOutputArtifactFilePath API to get an additional artifact path.
Then as part of OnPostprocessAllAssets, you can look for that path, and perform the side effects there.
The reason that this works is that OnPostprocessAllAssets is a special callback that happens after the imports (actual imports or cached imports).
This means that it is not cached, and therefore it will not introduce indeterminism.

13 Likes
6000.3.4f1 Startup Times
Reload Domain randomly stalls infinitely
In Case You Missed It - October 2025
2

I welcome these exceptions! It’s struck me as odd over the years how often something seems to be restored to expectations by deleting the /Library (so far, so normal) but then the issue will re-surface over time, or appear only for some users of the same project. I bet many of these can be attributed to this non-determinism.

Do I understand correctly that the non-determinism can only occur by using the listed methods within a ScriptedImporter, AssetPostProcessor or AssetModificationProcessor?

Will these methods also throw exceptions when they’re being called “too early” ie in static ctor and InitializeOnLoad(Method)?

4 Likes
4

Seems much safer. It’s better to have the determinism and be clear with the error rather than deal with irregular and inconsistent behavior that is difficult to debug. I’ve run into these issues before and did not have a good time - I’d be much happier with the target behavior.

Thanks for making a thread about the changes as these are commonly used API points.

6 Likes