supabase/supabase · error · Error

SNIPPETS_MANAGEMENT_FOLDER env var is not set. Please set it

Error message

SNIPPETS_MANAGEMENT_FOLDER env var is not set. Please set it to use snippets properly.

What it means

getFilesystemEntries — the foundation of every snippet/folder operation — refuses to run when SNIPPETS_DIR (from SNIPPETS_MANAGEMENT_FOLDER env var) is the empty string. Self-hosted snippets are stored on disk; without a configured root directory the entire feature is non-functional, so it fails loud rather than silently writing to cwd.

Source

Thrown at apps/studio/lib/api/snippets.utils.ts:144

  // Remove path traversal sequences and normalize
  const sanitized = path.basename(name)
  if (sanitized !== name || name.includes('\0')) {
    throw new Error('Invalid name: path traversal or null bytes detected')
  }
  return sanitized
}

/**
 * Gets a snapshot of the filesystem structure including files and folders.
 * Pass `includeContent: false` for listings (sidebar/folder tree), which only need metadata —
 * this skips reading every `.sql` file off disk.
 * @returns An array of files and folders with their metadata
 */
export async function getFilesystemEntries({
  includeContent = true,
}: { includeContent?: boolean } = {}): Promise<FilesystemEntry[]> {
  if (SNIPPETS_DIR === '') {
    throw new Error(
      'SNIPPETS_MANAGEMENT_FOLDER env var is not set. Please set it to use snippets properly.'
    )
  }

  // Ensure the snippets directory exists
  try {
    await fs.access(SNIPPETS_DIR)
  } catch {
    await fs.mkdir(SNIPPETS_DIR, { recursive: true })
  }

  const entries: FilesystemEntry[] = []

  const readEntriesRecursively = async (
    dirPath: string,
    folderName: string | null
  ): Promise<void> => {
    const items = await fs.readdir(dirPath, { withFileTypes: true })

View on GitHub (pinned to beee91b9c2)

Solutions

1. Set SNIPPETS_MANAGEMENT_FOLDER to an absolute, writable path in the Studio service env and restart.
2. Ensure the path is inside a persisted volume so snippets survive container restarts.
3. Verify the Studio process has read/write permissions on that directory.

Example fix

# before
# .env (missing)

# after
# .env
SNIPPETS_MANAGEMENT_FOLDER=/var/lib/studio/snippets

import { SNIPPETS_DIR } from './snippets.constants'
function assertSnippetsConfigured() {
  if (!SNIPPETS_DIR) {
    throw new Error('SNIPPETS_MANAGEMENT_FOLDER env var must be set')
  }
}

const isSnippetsConfigured = (): boolean => Boolean(process.env.SNIPPETS_MANAGEMENT_FOLDER)

try {
  await getFilesystemEntries()
} catch (e) {
  if (e instanceof Error && e.message.includes('SNIPPETS_MANAGEMENT_FOLDER')) {
    // show setup banner instead of crashing the snippets UI
    return []
  }
  throw e
}

When it happens

Trigger: Any snippets API route (list, get, save, delete, folder ops) is hit on a self-hosted instance where SNIPPETS_MANAGEMENT_FOLDER env var is unset/empty. Every snippet function funnels through getFilesystemEntries, so all of them surface this.

Common situations: New self-hosted deployment missing the env var in docker-compose/.env; the var was renamed; the Studio container started before the env was injected.

Related errors

• Failed to get count
• Internal Server Error
• Anon key not found in project settings
• Snippet with id ${snippetId} not found
• Snippet with id ${snippet.id} already exists

AI-assisted analysis of supabase/supabase@beee91b9c2 (2026-08-12). Data as JSON: /api/errors/da49b2bd986a164c. Report an issue: GitHub.