Agent skill

Flutter macOS Permission Handler Camera Failure

by divinevideo in divinevideo/divine-mobile

Fix silent camera/microphone failure on Flutter macOS when using permissionhandler plugin.

MPL-2.0Auto-check passedMobile

Install Flutter macOS Permission Handler Camera Failure

skills CLI
$ npx skills add divinevideo/divine-mobile --skill flutter-macos-permission-handler-camera-failure -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install divinevideo/divine-mobile flutter-macos-permission-handler-camera-failure --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/divinevideo/divine-mobile.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/flutter-macos-permission-handler-camera-failure .claude/skills/flutter-macos-permission-handler-camera-failure && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
flutter-macos-permission-handler-camera-failure
GitHub stars
266
Token cost
~1.5k tokens
SKILL.md length
433 words
Files
1
Skills in repo
103
Repo updated
First seen
Licence
MPL-2.0

At a glance

Fix silent camera/microphone failure on Flutter macOS when using permissionhandler plugin.

  • Works in 4 steps: Logs should show: 🔐 macOS detected -… → Permission state changes to… → Camera screen actually renders and… → …
  • Camera screen shows placeholder but no error on macOS
  • SKILL.md covers Problem, Context / Trigger Conditions, Root Cause and Solution, plus 6 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Flutter macOS Permission Handler Camera Failure is an agent skill from divinevideo/divine-mobile. Fix silent camera/microphone failure on Flutter macOS when using permissionhandler plugin. Use when: (1) Camera screen shows placeholder but no error on macOS, (2) CameraPermissionError state is emitted but cause is unclear, (3) permissionhandler checkCameraStatus() or checkMicrophoneStatus() throws exceptions on macOS desktop, (4) Camera works on iOS/Android but fails silently on macOS. The permissionhandler plugin doesn't work reliably on macOS - bypass it and let macOS handle permissions at the system level.

Its SKILL.md is about 1.5k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Mobile, covering Cross-platform mobile apps. It works with macOS, Flutter, Android and iOS. The licence is MPL-2.0.

When your agent uses it

  • Camera screen shows placeholder but no error on macOS
  • CameraPermissionError state is emitted but cause is unclear
  • Permissionhandler checkCameraStatus()
  • CheckMicrophoneStatus() throws exceptions on macOS desktop

Example prompts

  • “/flutter-macos-permission-handler-camera-failure”

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Logs should show: 🔐 macOS detected - bypassing permission_handler, assuming authorized
  2. Permission state changes to CameraPermissionLoaded with status authorized
  3. Camera screen actually renders and camera initialization logs appear
  4. macOS shows its native permission dialog on first camera access (if not already granted)

What it can do on your machine

Read from SKILL.md and the folder at commit 4c622be. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are dart).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • pub.dev
    • developer.apple.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Flutter macOS Permission Handler Camera Failure loads about 1.5k tokens when it runs. Until then it costs about 142 tokens; SKILL.md has 433 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~142
When it runs · the whole SKILL.md, loaded when a task matches
~1.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from divinevideo/divine-mobile at commit 4c622be, republished under its MPL-2.0 licence (© divinevideo). 433 words, ~1,465 tokens.

Download SKILL.mdSave it as .claude/skills/flutter-macos-permission-handler-camera-failure/SKILL.md (or your agent's skills folder).
name
flutter-macos-permission-handler-camera-failure
description
Fix silent camera/microphone failure on Flutter macOS when using permission_handler plugin. Use when: (1) Camera screen shows placeholder but no error on macOS, (2) CameraPermissionError state is emitted but cause is unclear, (3) permission_handler checkCameraStatus() or checkMicrophoneStatus() throws exceptions on macOS desktop, (4) Camera works on iOS/Android but fails silently on macOS. The permission_handler plugin doesn't work reliably on macOS - bypass it and let macOS handle permissions at the system level.
author
Claude Code
version
1.0.0
date
2026-01-28

Flutter macOS permission_handler Camera Failure

Problem

Camera/microphone permission checks using the permission_handler Flutter plugin throw exceptions on macOS desktop, causing permission gates to emit error states. The camera screen never renders, but the user sees a placeholder UI with no clear error message.

Context / Trigger Conditions

Use this skill when:

  • Flutter app works on iOS/Android but camera fails on macOS
  • Permission gate shows loading or error state on macOS
  • Logs show CameraPermissionError state being emitted
  • Permission.camera.status or Permission.microphone.status throws exceptions
  • Camera placeholder UI appears but VideoRecorderScreen (or equivalent) never initializes
  • No camera-related logs appear after navigation to camera screen

Key diagnostic pattern:

🔐 CameraPermissionGate initState
🔐 Building with state: CameraPermissionInitial
🔐 Triggering permission refresh
🔐 Permission state changed: CameraPermissionError  <-- This is the tell

Root Cause

The permission_handler plugin uses platform channels that don't work reliably on macOS desktop. When checkCameraStatus() or checkMicrophoneStatus() is called:

  • On iOS/Android: Returns proper permission status
  • On macOS: Throws exception → BLoC catches → Emits error state → Screen blocked

macOS handles camera/microphone permissions at the system level - the first time an app tries to access the camera, macOS shows its own permission dialog.

Solution

Bypass permission_handler on macOS and assume permissions are authorized:

dart
Future<void> _onRefresh(
  CameraPermissionRefresh event,
  Emitter<CameraPermissionState> emit,
) async {
  // On macOS desktop, permission_handler doesn't work reliably.
  // macOS handles camera permissions at the system level when the app
  // actually tries to access the camera, showing its own permission dialog.
  if (!kIsWeb && Platform.isMacOS) {
    emit(const CameraPermissionLoaded(CameraPermissionStatus.authorized));
    return;
  }

  // Normal permission check for iOS/Android
  try {
    final status = await checkPermissions();
    emit(CameraPermissionLoaded(status));
  } catch (e) {
    emit(const CameraPermissionError());
  }
}

Required imports:

dart
import 'dart:io';
import 'package:flutter/foundation.dart';

Verification

After implementing the fix:

  1. Logs should show: 🔐 macOS detected - bypassing permission_handler, assuming authorized
  2. Permission state changes to CameraPermissionLoaded with status authorized
  3. Camera screen actually renders and camera initialization logs appear
  4. macOS shows its native permission dialog on first camera access (if not already granted)
Show full SKILL.md (208 more words)Show less

Debugging Layers

When debugging silent camera failures, check these layers in order:

  1. Permission layer: Is the camera screen even being rendered? Check permission gate state.
  2. Initialization layer: Is initialize() being called? Check for initialization logs.
  3. Device detection layer: Are camera devices found? Check listDevices() results.
  4. Controller layer: Does camera controller initialize? Check for controller errors.

Add logging at each layer to trace where the flow stops.

When implementing this fix, also add:

  1. Error tracking in camera service: Add initializationError getter to report why camera failed (no devices, permission denied by macOS, etc.)

  2. UI error display: Pass error messages to placeholder widgets so users see what's wrong

  3. Try-catch around native calls: CameraMacOS.instance.listDevices() can also throw - wrap in try-catch and set error state

Example: Complete Fix

dart
// In CameraPermissionBloc
Future<void> _onRefresh(...) async {
  if (!kIsWeb && Platform.isMacOS) {
    log('macOS detected - bypassing permission_handler');
    emit(const CameraPermissionLoaded(CameraPermissionStatus.authorized));
    return;
  }
  // ... normal flow for mobile
}

// In CameraMacOSService
@override
Future<void> initialize() async {
  try {
    _videoDevices = await CameraMacOS.instance.listDevices(...);
  } catch (e) {
    _initializationError = 'Failed to detect cameras: $e';
    return;
  }

  if (_videoDevices?.isEmpty ?? true) {
    _initializationError = 'No camera found. Please connect a camera.';
    return;
  }
  // ... continue initialization
}

Notes

  • This is a platform-specific workaround, not a bug in your code
  • macOS Ventura+ has stricter permission handling; the native dialog will still appear
  • Test on actual macOS hardware, not just simulators
  • The camera_macos or camera_macos_plus packages handle the native permission dialog
  • Consider adding a "Camera permission required" UI that appears if macOS denies access

References

© divinevideo, MPL-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/flutter-macos-permission-handler-camera-failure of divinevideo/divine-mobile.

Open the folder on GitHubat commit 4c622be

Compare with similar skills

Flutter macOS Permission Handler Camera Failure next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Flutter macOS Permission Handler Camera Failure compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Flutter macOS Permission Handler Camera Failure this skilldivinevideo/divine-mobile266—~1.5kAutomated safety check: PassMPL-2.0
Engine Whats Newflutter/flutter179k—~978Automated safety check: PassBSD-3-Clause
flutter_soloud Setupalnitak/flutter_soloud424—~3.6kAutomated safety check: NotesMIT
Fkit SetupJoker-x-dev/FlutterKit127—~720Automated safety check: PassMIT
RunQuisApp/flutter_contacts111—~252Automated safety check: NotesMIT
Frb Dev Envfzyzcjy/flutter_rust_bridge5.4k—~5.5kAutomated safety check: PassMIT

Similar skills

  • Engine Whats New

    flutter/flutter

    Generates the "what's new" release summary and diff file for changes in the Flutter engine (//engine/src/flutter) between two releases (e.g., 3.47 vs 3.44).

    179k GitHub stars~978 tokensUpdated today
    MobileAuto-check passed
  • flutter_soloud Setup

    alnitak/flutter_soloud

    Walks through adding the flutter_soloud audio engine to a Flutter app, with per-platform setup, initialization, binary-size and logging options, and output device switching.

    424 GitHub stars~3.6k tokensUpdated yesterday
    MobileAuto-check: notes
  • Fkit Setup

    Joker-x-dev/FlutterKit

    将 FlutterKit 脚手架初始化为新的应用项目,统一修改应用显示名称、Dart 包名、Android Application ID、Apple Bundle ID、Linux/Windows 标识、Web 名称、运行时品牌文案、Logo、桌面图标和启动页。用户拉取模板后要求改名、改包名、替换品牌资源或完成首次项目配置时使用。

    127 GitHub stars~720 tokensUpdated 2 mo ago
    MobileAuto-check passed
  • Run

    QuisApp/flutter_contacts

    Run the example app on physical devices. An agent skill from QuisApp/flutter_contacts.

    111 GitHub stars~252 tokensUpdated 5 days ago
    MobileAuto-check: notes
  • Frb Dev Env

    fzyzcjy/flutter_rust_bridge

    A skill your agent uses when the user wants Docker-based FRB development or Tart-based iOS Simulator validation.

    5.4k GitHub stars~5.5k tokensUpdated yesterday
    MobileAuto-check passed
  • Embeds native Android, iOS, or macOS views into a Flutter app.

    130 GitHub stars~2.1k tokensUpdated 10 days ago
    MobileAuto-check passed

More from divinevideo/divine-mobile

All 103 skills in this repo
  • Fix ArgoCD ExternalSecret deployment failing with "namespace X is not permitted in project Y".

    266 GitHub stars~931 tokensUpdated today
    Auto-check passed
  • Art Direct

    divinevideo/divine-mobile

    Art direction for any content — reads text, PDF, Word, HTML, PPT, then proposes 2-3 creative directions with photography style, mood, and visual language.

    266 GitHub stars~4.8k tokensUpdated today
    Auto-check passed
  • Async Await Null Race Condition

    divinevideo/divine-mobile

    Fix "Null check operator used on a null value" errors when an object is set to null during an async await.

    266 GitHub stars~881 tokensUpdated today
    Auto-check passed
  • AWS V4 Signing Custom Headers Gcs

    divinevideo/divine-mobile

    Add custom metadata headers (x-amz-meta-) to AWS v4 signed requests for GCS S3-compatible API.

    266 GitHub stars~1k tokensUpdated today
    Auto-check passed
  • Bash Herestring Newline Secrets

    divinevideo/divine-mobile

    Fix password/secret authentication failures caused by trailing newlines when creating Google Cloud secrets (or similar) with bash here-strings.

    266 GitHub stars~791 tokensUpdated today
    Auto-check passed
  • Fix silent video/media processing failures caused by URL extraction code that filters on file extensions (.mp4, .webm, .webp).

    266 GitHub stars~1.1k tokensUpdated today
    Auto-check passed

Categories

Questions about Flutter macOS Permission Handler Camera Failure

What does Flutter macOS Permission Handler Camera Failure do?

Fix silent camera/microphone failure on Flutter macOS when using permissionhandler plugin. Flutter macOS Permission Handler Camera Failure is an agent skill from divinevideo/divine-mobile. Fix silent camera/microphone failure on Flutter macOS when using permissionhandler plugin.

When should I use Flutter macOS Permission Handler Camera Failure?

Flutter macOS Permission Handler Camera Failure fits situations like: camera screen shows placeholder but no error on macOS; cameraPermissionError state is emitted but cause is unclear; permissionhandler checkCameraStatus(); checkMicrophoneStatus() throws exceptions on macOS desktop.

How do I install Flutter macOS Permission Handler Camera Failure in Claude Code?

Run `npx skills add divinevideo/divine-mobile --skill flutter-macos-permission-handler-camera-failure -a claude-code`. Or copy the skill folder (.agents/skills/flutter-macos-permission-handler-camera-failure in divinevideo/divine-mobile) into .claude/skills/flutter-macos-permission-handler-camera-failure in your project. Claude Code loads it when a task matches its description.

How do I install Flutter macOS Permission Handler Camera Failure in Codex?

Run `npx skills add divinevideo/divine-mobile --skill flutter-macos-permission-handler-camera-failure -a codex`. Or copy the skill folder (.agents/skills/flutter-macos-permission-handler-camera-failure in divinevideo/divine-mobile) into .agents/skills/flutter-macos-permission-handler-camera-failure in your project. Codex loads it when a task matches its description.

Can I use Flutter macOS Permission Handler Camera Failure in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add divinevideo/divine-mobile --skill flutter-macos-permission-handler-camera-failure -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/flutter-macos-permission-handler-camera-failure, .gemini/skills/flutter-macos-permission-handler-camera-failure, .github/skills/flutter-macos-permission-handler-camera-failure and .opencode/skills/flutter-macos-permission-handler-camera-failure in your project.

What does Flutter macOS Permission Handler Camera Failure need to run?

SKILL.md names no scripts, command-line tools or credentials: Flutter macOS Permission Handler Camera Failure is instructions for the agent only.

Does Flutter macOS Permission Handler Camera Failure access the network?

SKILL.md names 2 domains. As links in the text: pub.dev and developer.apple.com. This is read from the text; nothing was executed.

Is Flutter macOS Permission Handler Camera Failure safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Flutter macOS Permission Handler Camera Failure use?

Flutter macOS Permission Handler Camera Failure is published under the MPL-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Flutter macOS Permission Handler Camera Failure use?

About 1.5k tokens (SKILL.md is roughly 5.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Flutter macOS Permission Handler Camera Failure?

Skills that share tags, products or a category with Flutter macOS Permission Handler Camera Failure: Engine Whats New (flutter/flutter, 179k stars), flutter_soloud Setup (alnitak/flutter_soloud, 424 stars), Fkit Setup (Joker-x-dev/FlutterKit, 127 stars) and Run (QuisApp/flutter_contacts, 111 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Flutter macOS Permission Handler Camera Failure?

divinevideo (a GitHub organization) maintains it in divinevideo/divine-mobile, which has 266 GitHub stars. The repository holds 103 skills in this directory. The repository was last updated on October 8, 2026.

Source: divinevideo/divine-mobile on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.