ramsey/uuid · error · BadMethodCallException

The method fromHexadecimal() does not exist on the provided

Error message

The method fromHexadecimal() does not exist on the provided factory

What it means

Uuid::fromHexadecimal() delegates to the globally registered factory (set via Uuid::setFactory()). The method is an extra capability beyond UuidFactoryInterface — only the default Ramsey\Uuid\UuidFactory (and subclasses) implement it. When the registered factory lacks fromHexadecimal(), the method_exists() capability check fails and a SPL BadMethodCallException is thrown. This is a guard for custom/test factories, not a flaw in normal usage.

Source

Thrown at src/Uuid.php:545

     * @throws InvalidArgumentException
     *
     * @pure
     */
    public static function fromHexadecimal(Hexadecimal $hex): UuidInterface
    {
        /** @phpstan-ignore possiblyImpure.methodCall */
        $factory = self::getFactory();

        if (method_exists($factory, 'fromHexadecimal')) {
            /** @phpstan-ignore possiblyImpure.methodCall */
            $uuid = $factory->fromHexadecimal($hex);
            /** @phpstan-ignore possiblyImpure.functionCall */
            assert($uuid instanceof UuidInterface);

            return $uuid;
        }

        throw new BadMethodCallException('The method fromHexadecimal() does not exist on the provided factory');
    }

    /**
     * Creates a UUID from a 128-bit integer string
     *
     * @param string $integer String representation of 128-bit integer
     *
     * @return UuidInterface A UuidInterface instance created from the string representation of a 128-bit integer
     *
     * @throws InvalidArgumentException
     *
     * @pure
     */
    public static function fromInteger(string $integer): UuidInterface
    {
        /** @phpstan-ignore possiblyImpure.methodCall */
        return self::getFactory()->fromInteger($integer);
    }

View on GitHub (pinned to da5b521600)

Solutions

1. Extend Ramsey\Uuid\UuidFactory with the custom factory instead of implementing UuidFactoryInterface — fromHexadecimal() is inherited
2. Add fromHexadecimal(Hexadecimal $hex): UuidInterface to the custom factory, delegating to an inner UuidFactory if wrapping one
3. Update test mocks/doubles to include the method
4. Guard the call site with method_exists(Uuid::getFactory(), 'fromHexadecimal') and choose an alternative construction path

Example fix

// before: minimal factory implementing only the interface
Uuid::setFactory(new class implements UuidFactoryInterface { /* ... */ });
$uuid = Uuid::fromHexadecimal($hex);
// BadMethodCallException: The method fromHexadecimal() does not exist on the provided factory

// after: extend the default factory, which has the method
Uuid::setFactory(new class extends UuidFactory {
    // custom behavior here; fromHexadecimal() inherited
});
$uuid = Uuid::fromHexadecimal($hex);

// Run before calling Uuid::fromHexadecimal()
if (!method_exists(Uuid::getFactory(), 'fromHexadecimal')) {
    // registered factory lacks the capability; use a supported path
    throw new \RuntimeException('Registered UUID factory does not support fromHexadecimal()');
}

use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\UuidFactory;

function factorySupportsFromHexadecimal(): bool
{
    return Uuid::getFactory() instanceof UuidFactory
        || method_exists(Uuid::getFactory(), 'fromHexadecimal');
}

try {
    $uuid = Uuid::fromHexadecimal($hex);
} catch (\BadMethodCallException $e) {
    // factory lacks the method: fix the factory registration
    throw new \RuntimeException('Replace the custom UUID factory or extend UuidFactory', 0, $e);
}

When it happens

Trigger: Calling Uuid::setFactory($factory) with a factory that only implements UuidFactoryInterface (or a PHPUnit mock/anonymous class without fromHexadecimal()), then calling Uuid::fromHexadecimal(new Hexadecimal('...')). The default factory never triggers this.

Common situations: DI containers binding a minimal custom factory; PHPUnit test doubles mocking UuidFactoryInterface; wrapper/decorator factories written from scratch instead of extending UuidFactory; static factories in legacy code predating the method.

Related errors

• The provided factory does not support the uuid7() method
• The provided factory does not support the uuid8() method
• Fields used to create a UuidV2 must represent a version 2 (D
• Fields used to create a UuidV3 must represent a version 3 (n
• Fields used to create a UuidV4 must represent a version 4 (r

AI-assisted analysis of ramsey/uuid@da5b521600 (2026-08-21). Data as JSON: /api/errors/3d6d148c4c25d235. Report an issue: GitHub.