Tencent/WeKnora · error

yuque connection failed: %w

Error message

yuque connection failed: %w

What it means

Connector.Validate pings GET /api/v2/user to verify credentials; any error from cli.Ping (transport failure, 401/403 ErrInvalidCredentials, 429 exhausted retries, 4xx/5xx API error, decode failure) is wrapped as "yuque connection failed: %w". This is the error surfaced when a user saves/tests a Yuque datasource configuration, so it aggregates every possible failure mode behind one wrapper. Use errors.Is/As on the wrapped chain to distinguish causes.

Source

Thrown at internal/datasource/connector/yuque/connector.go:38

// Connector implements datasource.Connector for Yuque.
type Connector struct{}

// NewConnector creates a new Yuque connector.
func NewConnector() *Connector { return &Connector{} }

// Type returns the connector type identifier.
func (c *Connector) Type() string { return types.ConnectorTypeYuque }

// Validate verifies the given credentials by pinging the current-user endpoint.
func (c *Connector) Validate(ctx context.Context, config *types.DataSourceConfig) error {
	cfg, err := parseYuqueConfig(config)
	if err != nil {
		return err
	}
	cli := newClient(cfg)
	if err := cli.Ping(ctx); err != nil {
		return fmt.Errorf("yuque connection failed: %w", err)
	}
	return nil
}

// ResolveResourceAncestors has nothing to do for Yuque: repositories are a flat
// list with no nesting, so a selection has no ancestors to reveal.
func (c *Connector) ResolveResourceAncestors(
	ctx context.Context, config *types.DataSourceConfig, resourceIDs []string,
) ([]string, error) {
	return []string{}, nil
}

// ListResources returns all repos (personal + team) accessible to the token.
// Serial fetch for v1 (user groups typically <10). TODO(perf): parallelize if slow.
func (c *Connector) ListResources(
	ctx context.Context, config *types.DataSourceConfig, parentID string,
) ([]types.Resource, error) {
	// Yuque resources are a flat list of repositories (no nesting), so a

View on GitHub (pinned to 988cbb0330)

Solutions

1. Unwrap with errors.Is(err, datasource.ErrInvalidCredentials) — if it matches, the token is bad: regenerate it in Yuque settings (Settings → Token) and update the datasource config.
2. Test the token manually: curl -H 'X-Auth-Token: <token>' https://www.yuque.com/api/v2/user and check the response.
3. Verify the configured base URL is reachable from the WeKnora deployment (DNS, proxy, firewall); note docker-compose containers may need the host network or proxy env.
4. If the error says rate limited, wait ~5 minutes and retry validation.
5. Ensure the config field mapping is right (api_token / base_url keys) and the token string is trimmed of whitespace.

Example fix

err := connector.Validate(ctx, cfg)
if err != nil {
    if errors.Is(err, datasource.ErrInvalidCredentials) {
        // bad token → prompt user to re-enter the API token
    } else if errors.Is(err, context.DeadlineExceeded) {
        // network/timeout → check connectivity to the Yuque host
    }
}

// Go: check token shape before calling Validate
token := strings.TrimSpace(cfg.APIToken)
if token == "" || len(token) < 16 {
    return errors.New("yuque api token missing or malformed — generate one in Yuque settings")
}
if !strings.HasPrefix(cfg.BaseURL, "https://") {
    return errors.New("yuque base url must be https")
}

// Go: classify the wrapped validation failure
func classifyValidateError(err error) string {
    switch {
    case errors.Is(err, datasource.ErrInvalidCredentials):
        return "invalid-credentials"
    case errors.Is(err, context.DeadlineExceeded), errors.Is(err, context.Canceled):
        return "timeout"
    case strings.Contains(err.Error(), "rate limited"):
        return "rate-limited"
    case strings.Contains(err.Error(), "decode response"):
        return "schema-mismatch"
    default:
        return "network-or-server"
    }
}

if err := connector.Validate(ctx, dsConfig); err != nil {
    switch classifyValidateError(err) {
    case "invalid-credentials":
        ui.ShowReconnectPrompt("yuque")
    case "rate-limited":
        time.Sleep(5 * time.Minute)
        retry()
    default:
        ui.ShowError(fmt.Sprintf("yuque connection failed: %v", err))
    }
    return
}

When it happens

Trigger: Validate(ctx, config) is called with credentials/baseURL whose /api/v2/user call fails: revoked or mistyped API token (401/403), unreachable host or timeout, exhausted rate limit (429 after 3 retries), 5xx after retry, non-2xx API error, or a 200 body that fails to decode.

Common situations: User pastes a token with whitespace/newline from a copy-paste; token was regenerated or expired; wrong baseURL for a private Yuque deployment; network egress blocked from the WeKnora deployment to yuque.com; token belongs to a deactivated account.

Related errors

• E2BAPIKey is required for the E2B backend
• S3 access key and secret key must be provided together
• failed to load AWS config: %w
• create tencent vectordb client: %w
• get current user: %w

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/97d260978360e5b2. Report an issue: GitHub.