siyuan-note/siyuan · error

walk notebook assets [%s] failed: %w

Error message

walk notebook assets [%s] failed: %w

What it means

When listing assets (ListAssetDir or similar scanning), each notebook's assets directory is walked with filelock.Walk. If the walk itself fails (not merely skipping a directory, which returns filepath.SkipDir), the function wraps the cause as "walk notebook assets [%s] failed" with the notebook's absolute path, aborting the whole listing.

Source

Thrown at kernel/model/assets.go:2778

							return filepath.SkipDir
						}
						return nil
					}
					relPath, relErr := assetPathMapKey(assetsDirPath, assetPath, d.IsDir())
					if relErr != nil {
						return relErr
					}
					assetsAbsPathMap[relPath] = assetPath
					return nil
				}); nestedWalkErr != nil {
					return nestedWalkErr
				}
				return filepath.SkipDir
			}
			return nil
		})
		if walkErr != nil {
			return nil, fmt.Errorf("walk notebook assets [%s] failed: %w", notebookAbsPath, walkErr)
		}
	}

	// 全局 assets
	dataAssetsAbsPath := util.GetDataAssetsAbsPath()
	walkErr := filelock.Walk(dataAssetsAbsPath, func(assetPath string, d fs.DirEntry, walkErr error) error {
		if walkErr != nil {
			return walkErr
		}
		if dataAssetsAbsPath == assetPath {
			return nil
		}

		if isSkipFile(d.Name()) {
			if d.IsDir() {
				return filepath.SkipDir
			}
			return nil

View on GitHub (pinned to 8641553a1f)

Solutions

1. Check kernel logs for the wrapped underlying walk error and fix the reported notebook directory (permissions, existence).
2. Ensure the notebook's assets directory exists and is readable by the kernel process.
3. Retry after sync/encryption passes complete if the directory was being transformed concurrently.
4. If the notebook directory is corrupt, restore it from sync/backup or remove and re-create the notebook.

try {
  const assets = await fetchPost('/api/asset/listAssetDir', {...});
} catch (e) {
  if (/walk notebook assets/.test(e.message)) {
    // underlying cause is in kernel logs; check permissions and retry after sync settles
    await retryAfterDelay(() => refetchAssets(), 3);
  }
}

When it happens

Trigger: Calling the asset-listing API while filelock.Walk over a notebook's assets folder returns an error — unreadable directory (permissions), the directory disappearing mid-walk (sync/encryption race), or I/O errors on the underlying filesystem.

Common situations: Permission problems after restoring a workspace as another user; encrypted-notebook decryption racing with the walk; the notebook folder being deleted or moved by sync during the scan; filesystem errors (bad sectors, network drives dropping).

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• asset path does not belong to a notebook: %s
• walk global assets [%s] failed: %w
• Query notebook failed
• Create notebook [%s] folder [%s] failed: %s
• Move notebook [%s] file [%s] failed: %s

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/5c81d336610db320. Report an issue: GitHub.