Troubleshooting

Delegation failed: invalid delegatee

Symptom: Creating a delegation fails with the error “Delegation failed: invalid delegatee” or similar validation error.Cause: You are using the session key DID (tc.sessionDid) instead of the primary DID (tc.did after signIn()) when specifying the delegatee. The server expects the delegatee to be the primary DID (e.g., did:pkh:eip155:{chainId}:{address} for Ethereum wallets), not session key format (did:key:z6Mk...).Solution: Use tc.did for user-to-user delegations. After signIn(), this returns the primary DID:

// Wrong - session key DID
await alice.createDelegation({ delegateDID: bob.sessionDid });

// Correct - primary DID (tc.did after signIn)
await alice.createDelegation({ delegateDID: bob.did });

See DID Formats for a detailed explanation of the primary vs session DID behavior.

Space does not exist

Symptom: Operations fail with “space does not exist” or “space not found” errors after authentication.Cause: The space has not been created yet. This happens when autoCreateSpace is disabled, or when an extension hook (like TinyCloudStorage.afterSignIn) runs before the space creation step completes.Solution: Ensure the space exists before performing operations:

const tc = new TinyCloudWeb({
  host: 'https://api.tinycloud.xyz',
  prefix: 'my-app',
  // Ensure space is created on first sign-in
  autoCreateSpace: true,
});

await tc.signIn();
// Space is now guaranteed to exist

If you have autoCreateSpace disabled and need manual control, call ensureSpaceExists() explicitly before any data operations.

Session expired

Symptom: Operations that previously worked now fail with authentication or session errors. You may see SESSION_EXPIRED or UNAUTHORIZED error codes.Cause: The session TTL has been exceeded. TinyCloud sessions have a limited lifetime for security.Solution: Detect expiry and re-authenticate:

if (tc.isSessionExpired()) {
  await tc.signIn();
}

For long-running services, use file-based session persistence and implement retry logic around session expiry. See Authentication for session persistence options.

WASM module not found

Symptom: Import errors or runtime errors about missing WASM modules when using the SDK. Common messages include Cannot find module '@tinycloud/sdk-rs' or WebAssembly module not found.Cause: The WASM package (@tinycloud/sdk-rs) was not built before the TypeScript wrappers. The build order matters because the TypeScript packages depend on WASM artifacts that must exist first.Solution: Rebuild in the correct order:

# In the web-sdk repository root

# 1. Build WASM artifacts first
cd packages/sdk-rs
bun run build

# 2. Then build the TypeScript wrappers
cd ../..
bun run build

The required build order is:

@tinycloud/sdk-rs — produces WASM artifacts
@tinycloud/node-sdk-wasm — TypeScript wrapper (depends on step 1)
@tinycloud/web-sdk-wasm — TypeScript wrapper (depends on step 1)

Running bun run build from the repository root without first building sdk-rs will fail. Always build WASM first.

Cannot signIn() in session-only mode

Symptom: Calling signIn() throws an error indicating that sign-in is not available, or that a private key is required.Cause: The TinyCloud instance was initialized without a privateKey (or without a connected wallet in the Web SDK). In session-only mode, there is no wallet available to sign the SIWE message that signIn() requires.Solution: Provide a private key when initializing the Node SDK:

// This will fail - no private key for signing
const tc = new TinyCloudNode({
  host: 'https://api.tinycloud.xyz',
  prefix: 'my-app',
  // Missing: privateKey
});
await tc.signIn(); // Error: cannot sign without private key

// Correct - provide a private key
const tc = new TinyCloudNode({
  host: 'https://api.tinycloud.xyz',
  prefix: 'my-app',
  privateKey: process.env.WALLET_PRIVATE_KEY,
});
await tc.signIn(); // Works

For the Web SDK, ensure the user has connected their wallet before calling signIn().

Share link has expired

Symptom: Receiving a share link (tc1:...) fails with an expiry-related error. The link was previously valid but no longer works.Cause: Share links contain an embedded delegation that has a set expiry time. Once that time passes, the link becomes permanently invalid.Solution: The original sharer must generate a new link with a fresh expiry:

const result = await tc.sharing.generate({
  path: 'my-document',
  expiry: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // New 7-day window
});

There is no way to extend the expiry of an existing link. Share links are immutable once generated because the delegation is cryptographically signed with the original expiry baked in.

When generating share links, choose an expiry that matches how long the link needs to be usable. Use shorter durations for sensitive data and longer durations for public content.

Sub-delegation rejected: path not within parent

Symptom: Creating a sub-delegation fails with a path constraint error.Cause: The path specified in the child delegation is not within the parent’s path scope. The server enforces that sub-delegations can only narrow access, never widen it.Solution: Ensure the child path is a sub-path of the parent:

// If parent delegation has path: /users/alice/*

// Valid child paths:
"/users/alice/*"              // Same scope
"/users/alice/docs/*"         // Narrower scope
"/users/alice/docs/readme.txt" // Specific file within scope

// Invalid child paths:
"/users/bob/*"    // Different user - outside parent scope
"/users/*"        // Broader than parent - cannot widen
"/admin/*"        // Unrelated path - outside parent scope

See Capabilities for the full constraint rules.

Sub-delegation rejected: expiry exceeds parent

Symptom: Creating a sub-delegation fails with an expiry constraint error.Cause: The child delegation’s expiry time is later than the parent’s expiry. Sub-delegations cannot outlive the capability they derive from.Solution: Set the child expiry to be equal to or earlier than the parent:

// Parent delegation expires at timestamp 1738800000

// Get parent expiry for reference
const parentExpiry = parentDelegation.expiry;

// Create child with same or earlier expiry
await tc.createSubDelegation({
  parentDelegation,
  delegateDID: bob.did,
  expiry: new Date(Date.now() + 24 * 60 * 60 * 1000), // Must be before parent's expiry
});

When specifying expiry, ensure the absolute timestamp is before the parent’s expiry. If the parent expires in 3 days, setting an expiry 7 days from now will fail.

Support

Still Having Issues?

Support

​Still Having Issues?

Still Having Issues?