cayleygraph/cayley · error

sql query failed: %v query: %v

Error message

sql query failed: %v
query: %v

What it means

Query wraps any error returned by database/sql's QueryContext with the message "sql query failed: %v\nquery: %v", attaching the generated SQL. It indicates the SQL sent by the SQL quadstore was rejected by the database (syntax, missing table/column, connection, permissions, etc.).

Source

Thrown at graph/sql/iterator.go:56

	vals := make([]interface{}, 0, len(args))
	for _, a := range args {
		vals = append(vals, a.SQLValue())
	}
	b := NewBuilder(qs.flavor.QueryDialect)
	qu := s.SQL(b)
	return qu, vals
}

func (qs *QuadStore) QueryRow(ctx context.Context, s Shape) *sql.Row {
	qu, vals := qs.prepareQuery(s)
	return qs.db.QueryRowContext(ctx, qu, vals...)
}

func (qs *QuadStore) Query(ctx context.Context, s Shape) (*sql.Rows, error) {
	qu, vals := qs.prepareQuery(s)
	rows, err := qs.db.QueryContext(ctx, qu, vals...)
	if err != nil {
		return nil, fmt.Errorf("sql query failed: %v\nquery: %v", err, qu)
	}
	return rows, nil
}

func (qs *QuadStore) newIterator(s Select) *Iterator {
	return &Iterator{
		qs:    qs,
		query: s,
	}
}

type Iterator struct {
	qs    *QuadStore
	query Select
	err   error
}

func (it *Iterator) Iterate() iterator.Scanner {

View on GitHub (pinned to 81dcd7d73e)

Solutions

1. Read the wrapped underlying error (%v) for the driver's root cause and the printed SQL.
2. Verify the database schema exists (run the store's Init/creation step) and the address points at the right database.
3. Confirm the correct SQL flavor for the backend when calling New/Init.
4. Check network/credentials and that the DB server is reachable.

rows, err := qs.Query(ctx, shape)
if err != nil {
    log.Printf("sql query failed: %v", err) // wrapped msg includes the SQL
    return err
}
defer rows.Close()

When it happens

Trigger: Calling Next/Contains on a SQL-backed iterator, which calls QuadStore.Query; the underlying db.QueryContext returns an error (bad SQL, missing table, dead connection, driver error).

Common situations: Connecting to a database where the schema tables don't exist (fresh DB, wrong database name); SQL flavor mismatch (MySQL query sent to Postgres); dropped connections or wrong credentials configured via the database address.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

• error executing value lookup: %w
• unsupported sql database: %q
• unsupported time format: %T: %v
• unmarshal value: %w
• ErrNoBucket

AI-assisted analysis of cayleygraph/cayley@81dcd7d73e (2026-09-06). Data as JSON: /api/errors/234ae487a859654a. Report an issue: GitHub.