ComposioHQ/composio · error · Error

Cannot determine save location: home directory is not availa

Error message

Cannot determine save location: home directory is not available

What it means

RemoteFile.save() needs a home directory to compute the default destination (~/.composio/temp-files/<filename>) when no explicit path is given, and platform.homedir() returned a falsy value in this runtime.

Source

Thrown at ts/packages/core/src/models/RemoteFile.ts:160

   * Downloads and saves the file to the local filesystem.
   * Requires a Node.js runtime with file system support (not available in Cloudflare Workers/Edge).
   *
   * @param path - Local path to save the file. If omitted, saves to the Composio temp directory using the filename from the mount path.
   * @returns The absolute path where the file was saved
   * @throws Error if file system is not supported or the save fails
   */
  async save(path?: string): Promise<string> {
    if (!platform.supportsFileSystem) {
      throw new Error(
        'File system operations are not supported in this runtime (e.g. Cloudflare Workers). ' +
          'Use buffer(), text(), or blob() to work with the file content in memory, or run in Node.js.'
      );
    }

    const content = await this.buffer();
    const homeDir = platform.homedir();
    if (!homeDir) {
      throw new Error('Cannot determine save location: home directory is not available');
    }

    const savePath =
      path ?? platform.joinPath(homeDir, COMPOSIO_DIR, TEMP_FILES_DIRECTORY_NAME, this.filename);

    const dir =
      path != null
        ? getParentDir(savePath)
        : platform.joinPath(homeDir, COMPOSIO_DIR, TEMP_FILES_DIRECTORY_NAME);
    if (dir && !platform.existsSync(dir)) {
      platform.mkdirSync(dir);
    }

    platform.writeFileSync(savePath, content);
    return savePath;
  }
}

View on GitHub (pinned to 64b1b85502)

Solutions

Pass an explicit absolute path: await file.save('/var/tmp/file.pdf')
Set HOME (or the platform's home env var) in the container/service environment
Pre-create the target directory if your runtime also restricts writes

Example fix

// before
await file.save();
// after
await file.save(path.join(os.tmpdir(), file.filename));

Defensive patterns

Strategy: validation

Validate before calling

const target = path ?? '/tmp/' + file.filename; // explicit path avoids homedir lookup
await file.save(target);

Type guard

const hasHomeDir = (): boolean => Boolean(platform.homedir());

Try / catch

try { await file.save(); } catch (e) { if (/home directory is not available/.test(String(e?.message))) { return file.save('/tmp/' + file.filename); } throw e; }

Prevention

Always pass an explicit absolute path to save() in containers
Set HOME in minimal Docker images
Verify the process user has a writable home or tmp dir

When it happens

Trigger: Calling await file.save() with no path in an environment where HOME/UserProfile is unset — containers with a bare env, certain serverless/edge sandboxes, or service accounts without a home dir.

Common situations: Docker images running with empty env; CI jobs scrubbing HOME; running under a daemon user with no home directory.

Related errors

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/d4b233bdbabbc935. Report an issue: GitHub.