Troubleshooting

Solutions to common issues with the BeatConnect SDK and build system.

Build Failures

CMake Configuration Failed

Error:

CMake Error at CMakeLists.txt:3 (project):
  No CMAKE_CXX_COMPILER could be found.

Cause: Compiler not found on build machine.

Solution: This is a BeatConnect infrastructure issue. Contact support if this persists.

---

Error:

CMake Error: add_subdirectory given source "external/JUCE" which is not a directory.

Cause: JUCE submodule not initialized.

Solution:

# Initialize submodules locally
git submodule update --init --recursive
 
# Commit .gitmodules if missing
git add .gitmodules external/JUCE
git commit -m "Add JUCE submodule"
git push

---

Error:

CMake Error: Unknown CMake command "juce_add_plugin".

Cause: JUCE not included before using its commands.

Solution: Ensure correct order in CMakeLists.txt:

# First: add JUCE
add_subdirectory(external/JUCE)
 
# Then: use JUCE commands
juce_add_plugin(MyPlugin ...)

Compilation Failed

Error:

error: use of undeclared identifier 'MyClass'

Cause: Missing source file or include.

Solution: Check target_sources() includes all your .cpp files:

target_sources(MyPlugin PRIVATE
    Source/PluginProcessor.cpp
    Source/PluginEditor.cpp
    Source/MyClass.cpp          # Add missing files
)

---

Error:

error: 'BinaryData.h' file not found

Cause: Binary resources not properly configured.

Solution:

juce_add_binary_data(PluginResources
    SOURCES
        Resources/image.png
)
 
target_link_libraries(MyPlugin PRIVATE PluginResources)

---

Error:

Undefined symbols for architecture arm64:
  "_someFunction", referenced from: ...

Cause: Missing library or arm64-incompatible dependency.

Solution:

1. Check all dependencies support arm64
2. Ensure all libraries are linked:

target_link_libraries(MyPlugin PRIVATE
    missing_library
)

Linking Failed

Error:

ld: library not found for -lsomething

Cause: External library not found.

Solution:

1. Add library to external/ directory
2. Configure in CMake:

add_subdirectory(external/something)
target_link_libraries(MyPlugin PRIVATE something)

---

Error:

duplicate symbol '_main' in: ...

Cause: Multiple main() functions (often from Standalone format).

Solution: Ensure only one entry point, or disable Standalone:

FORMATS VST3 AU   # Remove Standalone if not needed

Code Signing Issues

Notarization Failed

Error:

[Notarization] Failed: The signature of the binary is invalid.

Cause: Binary was modified after signing, or unsigned code included.

Solution:

1. Ensure all linked libraries are signed
2. Don’t modify the bundle after building
3. Check for unsigned frameworks:

codesign -vvv --deep YourPlugin.vst3

---

Error:

[Notarization] Failed: The executable contains code that doesn't match the signature.

Cause: Hardened Runtime issue.

Solution: This is handled by BeatConnect. Contact support if this persists.

Windows Signing Failed

Error:

[Signing] SignTool Error: No certificates were found

Cause: Certificate issue on build system.

Solution: This is a BeatConnect infrastructure issue. Contact support.

GitHub Integration

Repository Not Found

Error:

Repository "username/repo" not found or not accessible.

Causes:

1. GitHub App doesn’t have access
2. Repository is archived
3. Repository was deleted

Solution:

1. Go to GitHub → Settings → Applications
2. Configure BeatConnect app
3. Add the repository to allowed list

Installation Not Found

Error:

GitHub installation not found for this account.

Cause: GitHub App was uninstalled.

Solution:

1. Go to Creator Portal → Settings → Developer
2. Disconnect GitHub
3. Reconnect with “Connect GitHub”

Permission Denied

Error:

Resource not accessible by integration.

Cause: GitHub App permissions insufficient.

Solution:

1. Re-authorize the GitHub App
2. Grant necessary permissions
3. For organization repos, ask admin to approve

License Activation

Activation Failed

Error:

{
  "error": "max_activations_reached"
}

Cause: License has reached maximum allowed machines.

Solution:

1. Deactivate from an old machine
2. Increase max_activations (for new keys)
3. Contact creator for additional activations

---

Error:

{
  "error": "code_revoked"
}

Cause: License was revoked by creator.

Solution: Contact the plugin creator for a new license.

---

Error:

{
  "error": "code_not_found"
}

Cause: Activation code is invalid.

Solution:

1. Check for typos in the code
2. Verify code format (UUID)
3. Confirm purchase was completed

Validation Fails After Working

Possible Causes:

1. Network issue — Check internet connection
2. License revoked — Check with creator
3. Machine ID changed — Hardware upgrade

Solution:

// Handle validation gracefully
if (!activationManager.validate())
{
    // Check if it's a network issue
    if (!hasNetworkConnection())
    {
        // Allow temporary offline use
        return useOfflineGracePeriod();
    }
 
    // Show reactivation dialog
    showReactivationDialog();
}

Build Quota

Quota Exceeded

Error:

{
  "error": "quota_exceeded",
  "message": "Monthly build limit reached"
}

Solution:

1. Wait for quota reset (first of month)
2. Purchase additional builds ($5 each)
3. Upgrade to Team tier for more builds

Build Counted Despite Failure

Policy:

• Your code errors → counts against quota
• Our infrastructure errors → doesn’t count

If you believe a build was incorrectly counted:

1. Check build logs for error type
2. Contact support with build ID

Plugin Loading Issues

Plugin Doesn’t Appear in DAW

Possible Causes:

1. Wrong plugin folder
2. Quarantine attribute (macOS)
3. DAW cache needs refresh

Solutions:

macOS VST3:

# Check plugin location
ls ~/Library/Audio/Plug-Ins/VST3/
 
# Remove quarantine
xattr -d com.apple.quarantine ~/Library/Audio/Plug-Ins/VST3/YourPlugin.vst3
 
# Refresh DAW plugin cache
# In your DAW: Preferences → Plugins → Rescan

Windows VST3:

# Check plugin location
dir "C:\Program Files\Common Files\VST3\"
 
# Verify signature
Get-AuthenticodeSignature ".\YourPlugin.vst3"

Plugin Crashes on Load

Diagnosis:

# macOS: Check crash logs
ls ~/Library/Logs/DiagnosticReports/*YourPlugin*
 
# View crash log
cat ~/Library/Logs/DiagnosticReports/YourPlugin*.crash

Common Causes:

1. Missing dependency
2. Null pointer in constructor
3. Invalid parameter initialization

Debug locally:

// Add logging to constructor
DBG("Plugin constructor started");
 
// Check for null before use
if (somePointer != nullptr)
{
    somePointer->doSomething();
}

Audio Crackles or Glitches

Possible Causes:

1. Buffer size issues
2. Denormal numbers
3. Heavy processing

Solutions:

// Add denormal protection
void processBlock(AudioBuffer<float>& buffer, MidiBuffer&)
{
    ScopedNoDenormals noDenormals;
 
    // Your processing...
}

// Check buffer size
void prepareToPlay(double sampleRate, int samplesPerBlock)
{
    // Don't assume buffer size
    maxBlockSize = samplesPerBlock;
 
    // Prepare for any buffer size up to max
    delayBuffer.setSize(2, (int)(sampleRate * maxDelaySeconds));
}

Network Issues

Build Callbacks Not Received

Possible Causes:

1. Firewall blocking
2. VPN interference
3. Webhook URL incorrect

Solution: Ensure your firewall allows:

• Outbound HTTPS (port 443)
• Connections to api.beatconnect.com

API Timeouts

Error:

Error: Request timeout after 30000ms

Solutions:

1. Check your internet connection
2. Try again in a few minutes
3. Use exponential backoff:

int retries = 3;
int delayMs = 1000;
 
for (int i = 0; i < retries; i++)
{
    auto response = makeRequest();
    if (response.isSuccess())
        return response;
 
    Thread::sleep(delayMs);
    delayMs *= 2;  // Exponential backoff
}

Getting Help

Before Contacting Support

1. Check build logs — Most errors are explained there
2. Test locally — Ensure it builds on your machine
3. Check this page — Most common issues are covered
4. Search Discord — Others may have had the same issue

Information to Provide

When contacting support, include:

1. Build ID — build_abc123...
2. Error message — Exact error text
3. Build logs — Download and attach
4. Repository — Link (if public) or description
5. Steps to reproduce — What you did before the error

Contact Options

• Discord: BeatConnect Community
• Email: support@beatconnect.com
• GitHub Issues: For SDK bugs

Next Steps

• Frequently Asked Questions
• Build System Reference
• API Documentation