What causes "syn::Error::new(span, message)" in sinelaw/fresh?

Read the accompanying compiler message at the pointed span and fix the offending token

syn::Error::new(span, message)

Error message

syn::Error::new(span, message)

What it means

This is the macro crate's helper that converts a `syn::Error` into a `proc_macro2::TokenStream` compile error, so any classification/validation failure in `plugin_api_impl` surfaces at compile time with the offending span. The message shown is the generic constructor call site; the actual text comes from the macro's validation logic.

Solutions

Read the accompanying compiler message at the pointed span and fix the offending token
Match the API method signature patterns documented for the macro (supported arg/return types)
Check the macro crate's docs/examples for the accepted item shape
File an issue if a valid signature is wrongly rejected

Example fix

// before
fn read(&self, cb: fn(Vec<u8>));
// after
fn read(&self, cb: fn(PluginResult<Vec<u8>>));

Defensive patterns

Strategy: try-catch

Try / catch

// This is a compile-time error: fix the macro input; cannot be caught at runtime.
// Read the spanned message from cargo output and adjust the API definition to match
// the macro's supported method shapes.

Prevention

Copy method signatures from the macro crate's documented examples
Avoid exotic parameter/return types in plugin API definitions
Run cargo check early and often when authoring plugin APIs
Pin and read the changelog when upgrading the macro crate for newly rejected shapes

When it happens

Trigger: Using the `plugin_api!` (or equivalent) macro on an item the macro cannot classify — e.g. a trait method whose signature doesn't match expected patterns, unsupported types, or malformed API definitions.

Common situations: Plugin authors writing an API method with an unsupported parameter/return type; misplacing attributes the macro expects; upgrading the macro crate and using newly rejected shapes.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of sinelaw/fresh@67894ca546 (2026-09-13). Data as JSON: /api/errors/50b6c24865048807. Report an issue: GitHub.

Appendix: source

Thrown at crates/fresh-plugin-api-macros/src/lib.rs:102

//! 2. **Explicit Over Implicit**: No magic naming conventions, use attributes
//! 3. **Deterministic Output**: Same input always produces same output
//! 4. **Preserve Original Code**: Macro passes through impl block unchanged
//! 5. **Clear Errors**: Compile-time errors with helpful messages

use proc_macro::TokenStream;
use quote::{format_ident, quote};
use syn::{
    parse_macro_input, spanned::Spanned, Attribute, FnArg, GenericArgument, ImplItem, ImplItemFn,
    ItemImpl, Meta, Pat, PathArguments, ReturnType, Type,
};

// ============================================================================
// Error Handling
// ============================================================================

/// Create a compile error with a helpful message and source span
fn compile_error(span: proc_macro2::Span, message: &str) -> proc_macro2::TokenStream {
    syn::Error::new(span, message).to_compile_error()
}

// ============================================================================
// API Method Classification
// ============================================================================

/// Classification of API method return behavior
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ApiKind {
    /// Synchronous method - returns value directly
    Sync,
    /// Async method returning `Promise<T>`
    AsyncPromise,
    /// Async method returning `ProcessHandle<T>` (cancellable)
    AsyncThenable,
}

impl ApiKind {

View on GitHub (pinned to 67894ca546)