What causes "Index ${indexName} not found" in ruvnet/ruflo?

Confirm the index exists: query pg_indexes (schemaname, indexname) or \di in psql for the exact name

Index ${indexName} not found

Error message

Index ${indexName} not found

What it means

Thrown by the index-stats lookup when the query against pg_stat_user_indexes returns zero rows for the given index name. The stats view only lists indexes that exist in the current schema's user tables, so no row means the index was never created, lives in a different schema, or the name is misspelled.

Source

Thrown at v3/@claude-flow/plugins/src/integrations/ruvector/ruvector-bridge.ts:946

      indexrelname: string;
      idx_scan: number;
      idx_tup_read: number;
      idx_tup_fetch: number;
      pg_relation_size: number;
    }>(
      `SELECT
        indexrelname,
        idx_scan,
        idx_tup_read,
        idx_tup_fetch,
        pg_relation_size(indexrelid) as pg_relation_size
      FROM pg_stat_user_indexes
      WHERE indexrelname = $1`,
      [indexName]
    );

    if (result.rows.length === 0) {
      throw new Error(`Index ${indexName} not found`);
    }

    const row = result.rows[0];
    return {
      indexName: row.indexrelname,
      indexType: 'hnsw', // Would need additional query to determine
      numVectors: row.idx_tup_read,
      sizeBytes: row.pg_relation_size,
      buildTimeMs: 0, // Not available from stats
      lastRebuild: new Date(),
      params: {
        scans: row.idx_scan,
        tuplesRead: row.idx_tup_read,
        tuplesFetched: row.idx_tup_fetch,
      },
    };
  }

View on GitHub (pinned to fa13ee4ad6)

Solutions

Confirm the index exists: query pg_indexes (schemaname, indexname) or \di in psql for the exact name
Create the index first (bridge.createIndex) and only then fetch stats
For non-default schemas, use the schema-qualified name or set the pool's search_path so pg_stat_user_indexes can see it

Example fix

// before
const stats = await bridge.getIndexStats('idx_missing'); // throws

// after
await bridge.createIndex({ tableName: 'vectors', columnName: 'embedding', indexType: 'hnsw' });
const stats = await bridge.getIndexStats('idx_vectors_embedding_hnsw');

Defensive patterns

Strategy: validation

Validate before calling

const exists = await bridge.query(
  `SELECT 1 FROM pg_indexes WHERE indexname = $1`,
  [indexName]
);
if (exists.rows.length === 0) {
  throw new Error(`Index '${indexName}' does not exist — create it before reading stats`);
}
const stats = await bridge.getIndexStats(indexName);

Try / catch

try {
  return await bridge.getIndexStats(indexName);
} catch (err) {
  if (err instanceof Error && err.message.endsWith('not found')) {
    return null; // treat missing index as 'no stats yet'
  }
  throw err;
}

Prevention

Run createIndex migrations before maintenance jobs that poll stats
Use schema-qualified names or set search_path when the index lives outside public
Handle the not-found case gracefully in monitoring loops (index may be mid-rebuild with replace: true)

When it happens

Trigger: Calling getIndexStats before createIndex ran; checking an index created in a non-default schema while the connection's search_path points elsewhere; querying stats for an index that createIndex(replace: true) just dropped.

Common situations: Deployment ordering — a monitoring/maintenance job polls stats before the migration that builds the index; multi-schema databases where the pool connects without setting search_path; index renamed or dropped by a concurrent migration.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/fb70b555c39031bc. Report an issue: GitHub.