What causes "check share id availability: %w" in AlistGo/alist?

Inspect the wrapped error for the DB root cause (connection refused, lock timeout, etc.)

check share id availability: %w

Error message

check share id availability: %w

What it means

While resolving a share ID for creation (excludeID == 0 path), the database uniqueness check db.ShareIDExists(shareID) itself returned an error; it is wrapped as 'check share id availability: %w'. This is a data-layer failure, not a duplicate-ID conflict (that returns errShareIDExists instead).

Source

Thrown at server/handles/share.go:233

	}
	return nil
}

func resolveRequestedShareID(rawShareID, fallback string, excludeID uint) (string, error) {
	shareID := strings.TrimSpace(rawShareID)
	if shareID == "" {
		if fallback != "" {
			return fallback, nil
		}
		return generateShareID()
	}
	if err := validateCustomShareID(shareID); err != nil {
		return "", err
	}
	if excludeID == 0 {
		exists, err := db.ShareIDExists(shareID)
		if err != nil {
			return "", fmt.Errorf("check share id availability: %w", err)
		}
		if exists {
			return "", errShareIDExists
		}
		return shareID, nil
	}
	exists, err := db.ShareIDExistsExceptID(shareID, excludeID)
	if err != nil {
		return "", fmt.Errorf("check share id availability: %w", err)
	}
	if exists {
		return "", errShareIDExists
	}
	return shareID, nil
}

func normalizeShareAccessLimit(accessLimit int64, burnAfterRead *bool) (int64, bool, error) {
	if accessLimit < 0 {

View on GitHub (pinned to 843d9dc814)

Solutions

Inspect the wrapped error for the DB root cause (connection refused, lock timeout, etc.)
Restore DB connectivity and retry the request
For SQLite, reduce concurrent write traffic or move to a client-server DB
Verify the schema is migrated (x_shares table and columns exist)

Defensive patterns

Strategy: try-catch

Validate before calling

if err := db.Ping(); err != nil {
    return fmt.Errorf("db unavailable, deferring share creation: %w", err)
}

Try / catch

if err := resolveShareID(req.ShareID, "", 0); err != nil {
    if strings.Contains(err.Error(), "check share id availability") {
        // data-layer failure: check DB health, then retry; do not tell the user the ID is taken
    }
}

Prevention

Monitor DB connectivity in health checks
Avoid SQLite write concurrency storms during share creation
Keep migrations applied so ShareIDExists queries never fail structurally

When it happens

Trigger: Creating a share while the database is unreachable, the x_shares table is locked/corrupt, or the DB connection pool is exhausted.

Common situations: Database downtime or restart during share creation; SQLite lock contention under concurrent writes; migration leaving the shares table in a bad state.

Related errors

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/fa9436bc19596ec2. Report an issue: GitHub.